DICOMweb Documentation

Introduction & General Information

This document provides a comprehensive technical guide for the DICOMweb API functions with example methods that are used through a C# example application. It includes detailed explanations of all available functions, covering both standard DICOMweb services (such as QIDO-RS, WADO-RS, and STOW-RS) and custom DICOMweb API endpoints developed by PostDICOM. These functions are designed to be used in server side calls.

To use PostDICOM’s DICOMweb services, you must first have this feature enabled for your account and possess valid user credentials. If DICOMweb access is not yet activated for your account and you wish to integrate your application with PostDICOM, please contact us to request activation.

User Name: This is your primary login credential, usually your email address. It is unique to your account and used as the username in Basic Authentication.

Password: This is the password associated with your PostDICOM account. It is used in conjunction with your username during Basic Authentication. For optimal security, we strongly recommend choosing a strong password. Please have necessary security mechanisms on your server side call so that this username and password is protected by yourself.

You can manage your password and security settings through your account profile page after you login to your PostDICOM account

---

DICOMweb Standard Services

Store DICOM Instances (STOW-RS)

This function orchestrates the uploading of all .dcm files from a specified local folder to the DICOMweb server. It first identifies all relevant files, then uses helper methods to construct and send an authenticated multipart/related POST request for each file, adhering to the STOW-RS standard.

Required Parameters	Data Type	Description
UserName	string	The username (email address) for the PostDICOM account. (from initialization)
Password	string	The password associated with the PostDICOM account. (from initialization)
WebAddress	string	The base URL of the API. (from initialization)
DirectoryPath	string	The full path to the local directory containing the DICOM (.dcm) files to be uploaded.

Query for DICOM Objects (QIDO-RS)

This function performs a query for DICOM objects using the QIDO-RS standard, enabling searches at the Study, Series, or Instance level. Based on the provided search parameter (such as Patient ID, Study Instance UID, or Series Instance UID), it constructs the appropriate URL and executes an authenticated request to retrieve matching results from the server.

Required Parameters	Data Type	Description
UserName	string	The username (email address) for the PostDICOM account. (from initialization)
Password	string	The password associated with the PostDICOM account. (from initialization)
WebAddress	string	The base URL of the API. (from initialization)
PatientID	string	Optional. Used to identify the patient and search for related studies.
StudyInstanceUID	string	Optional. Used to search for a specific study or all series within that study.
SeriesInstanceUID	string	Optional. Used to search for all image instances within a specific series.

Retrieve DICOM Instances (WADO-RS)

This function provides an interactive menu to retrieve DICOM objects using the WADO-RS standard. The user selects a retrieval level (Study, Series, or Instance) and provides the corresponding UID. The function then makes an authenticated request and processes the multipart/related response, saving each DICOM part as a separate .dcm file to a newly created local directory.

Required Parameters	Data Type	Description
UserName	string	The username (email address) for the PostDICOM account. (from initialization)
Password	string	The password associated with the PostDICOM account. (from initialization)
WebAddress	string	The base URL of the API. (from initialization)
StudyInstanceUID	string	Optional. A globally unique identifier for a DICOM study. Used to retrieve all series and instances associated with that study.
SeriesInstanceUID	string	Optional. A globally unique identifier for a series within a DICOM study. Used to retrieve all images under that series.
SOPInstanceUID	string	Optional. A unique identifier for an individual DICOM image instance. Used to retrieve a specific image using WADO-RS.

---

Sharing Management

Create Share Link

This function generates a secure web link to share one or more patient orders with external users. The link can be password protected and optionally allow downloads.

Required Parameters	Data Type	Description
UserName	string	The username (email) for the PostDICOM account. (from initialization)
Password	string	The password for the PostDICOM account. (from initialization)
WebAddress	string	The base URL of the API. (from initialization)
PatientOrderInfoList	List	List of JSON strings, each containing a "PatientOrderUuid" key, identifying the patient orders to be shared.
ExpireDate	string (YYYY-MM-DD)	Expiration date for the share link. After this date, the link will be disabled.
SharePassword	string	Optional. Password required to access the share link. Leave empty for public access.
Downloadable	bool	Optional. Determines whether the DICOM studies are downloadable by the recipient.

Share Patient Order with URL

This function generates a shareable URL for selected patient orders with additional access control options such as download permission and password protection.

Required Parameters	Data Type	Description
UserName	string	The username (email) of the PostDICOM account. (from initialization)
Password	string	The password for the PostDICOM account. (from initialization)
WebAddress	string	The base URL of the API. (from initialization)
OrderUuidList	List	List of UUIDs identifying patient orders to be shared.
ExpireDate	string (YYYY-MM-DD)	Date after which the share link becomes inactive.
SharePassword	string	Optional. Password required to access the shared link.
UserCanDownloadStudies	bool	Optional. If set to true, the recipient can download the studies.

---

Folder & Order Management

Create Folder

This function is used to create a new folder (a virtual container) within the PostDICOM account to help organize patient orders.

Required Parameters	Data Type	Description
UserName	string	The username (email address) for the PostDICOM account. (from initialization)
Password	string	The password associated with the PostDICOM account. (from initialization)
WebAddress	string	The base URL of the API. (from initialization)
FolderName	string	Required. The visible name for the new folder.
FolderDescription	string	Optional. A text description for the folder.
ParentFolderUuid	string	Optional. The UUID of an existing folder to create the new folder inside it.

Search Folder

This function finds existing folders based on search criteria. It can optionally include the list of patient orders within each found folder.

Required Parameters	Data Type	Description
UserName	string	The username (email address) for the PostDICOM account. (from initialization)
Password	string	The password associated with the PostDICOM account. (from initialization)
WebAddress	string	The base URL of the API. (from initialization)
ParentFolderUuid	string	Optional. A folder UUID to restrict the search to its children.
FolderName	string	Optional. A full or partial name to search for.
GetOrdersInFolder	bool	Optional. If `true`, the response will include a list of patient orders for each folder found.

Share Folder with URL

This function generates a secure, shareable URL for an entire folder and its contents. It allows for comprehensive access control by setting a custom title, description, a password, an expiration date, and specifying whether the contents can be downloaded by the recipient.

Required Parameters	Data Type	Description
UserName	string	The username (email address) for the PostDICOM account. (from initialization)
Password	string	The password associated with the PostDICOM account. (from initialization)
WebAddress	string	The base URL of the API. (from initialization)
FolderUuid	string	Required. The unique identifier (UUID) of the folder to be shared.
SharePassword	string	Optional. A password to protect the shared link. If left empty, the link will be publicly accessible.
ShareTitle	string	Optional. A custom title for the shared folder page, visible to the recipient.
ShareDescription	string	Optional. A description displayed on the shared folder page.
ExpireDate	string (YYYY-MM-DD)	Optional. The date on which the share link will automatically become inactive.
UserCanDownloadStudies	bool	Optional. If `true`, recipients can download the patient orders contained within the folder.

Add Order to Folder

This function creates an association between an existing patient order and an existing folder. This is an organizational tool; it does not move or copy data.

Required Parameters	Data Type	Description
UserName	string	The username (email address) for the PostDICOM account. (from initialization)
Password	string	The password associated with the PostDICOM account. (from initialization)
WebAddress	string	The base URL of the API. (from initialization)
PatientOrderUuid	string	Required. The UUID of the patient order to be placed into a folder.
FolderUuidList	List	Required. A list containing the UUID of the destination folder.

---

Workflow & Assignment

Assign Order to User

This function is a core workflow tool. It assigns a patient order to an individual user, signifying that this user is now responsible for a task related to that order (e.g., reporting).

Required Parameters	Data Type	Description
UserName	string	The username (email address) for the PostDICOM account. (from initialization)
Password	string	The password associated with the PostDICOM account. (from initialization)
WebAddress	string	The base URL of the API. (from initialization)
PatientOrderUuid	string	Required. The UUID of the patient order that requires action.
AssignedUserUuid	string	Required. The UUID of the specific user who will be assigned responsibility.

Assign Order to User Group

Similar to assigning to a single user, this function assigns a patient order to an entire group, enabling team-based workflows where any group member can handle the task.

Required Parameters	Data Type	Description
UserName	string	The username (email address) for the PostDICOM account. (from initialization)
Password	string	The password associated with the PostDICOM account. (from initialization)
WebAddress	string	The base URL of the API. (from initialization)
PatientOrderUuid	string	Required. The UUID of the patient order to be assigned to the group.
AssignedUserGroupUuid	string	Required. The UUID of the user group to be assigned the order.

---

Patient Order Lifecycle & Data Retrieval

Create Patient Order

This function creates a new patient order to schedule and manage imaging studies within the system. Required parameters must be provided for successful creation.

Required Parameters	Data Type	Description
InstitutionUuid	string	Required. UUID of the institution where the patient order is being created.
PatientName	string	Required. Full name of the patient.
PatientId	string	Required. Patient's unique identifier such as a national ID or MRN.
PatientBirthdate	string (YYYY-MM-DD)	Required. Patient's birth date in ISO format.
Modality	string	Required. Modality type such as CT, MR, US, etc.
OtherPatientId	string	Optional. An additional identifier for the patient, if applicable.
PatientSex	string	Optional. Patient's gender (e.g., M, F, O).
StudyDescription	string	Optional. Description of the imaging study being ordered.
AccessionNumber	string	Optional. Unique accession number for the order, if applicable.
PatientComplaints	string	Optional. Text describing the patient's complaints or symptoms.
OrderScheduledDatetime	string (YYYY-MM-DD HH:MM)	Optional. The scheduled start date and time of the procedure.
RequestedProcedureId	string	Optional. Identifier for the requested procedure.
RequestedProcedureDescription	string	Optional. Description of the requested procedure.
RequestingPhysician	string	Optional. Name of the physician who requested the study.
ReferringPhysiciansName	string	Optional. Name of the referring physician, if different from requesting.
ScheduledEquipmentUuid	string	Optional. UUID of the imaging equipment to be used for the scheduled procedure.

Get Patient Order Properties

This function retrieves the complete set of properties for a single, specific patient order.

Required Parameters	Data Type	Description
UserName	string	The username (email address) for the PostDICOM account. (from initialization)
Password	string	The password associated with the PostDICOM account. (from initialization)
WebAddress	string	The base URL of the API. (from initialization)
PatientOrderInstitutionUuid	string	Required. The UUID of the institution to which the order belongs.
PatientOrderUuid	string	Required. The UUID of the specific patient order to retrieve.

Search for Patient Orders

This function retrieves a list of patient orders based on a combination of search filters such as patient name, ID, modality, and study or birth dates. It enables advanced search functionality for institutions managing multiple orders.

Required Parameters	Data Type	Description
UserName	string	The username (email address) for the PostDICOM account. (from initialization)
Password	string	The password associated with the PostDICOM account. (from initialization)
WebAddress	string	The base URL of the API. (from initialization)
InstitutionUuidList	List	List of UUIDs identifying the institutions to search for patient orders.
PatientName	string	Optional. Filter by patient's full name.
PatientId	string	Optional. Filter by patient's unique identifier.
OtherPatientId	string	Optional. Secondary identifier for the patient, if available.
AccessionNumber	string	Optional. Filter by accession number assigned to the study.
ModalityList	List	List of modalities (e.g., CT, MR, US) to filter the search results.
StudyDateFrom	string (YYYY-MM-DD)	Optional. Start date of the study date range for filtering results.
StudyDateTo	string (YYYY-MM-DD)	Optional. End date of the study date range for filtering results.
PatientBirthdateFrom	string (YYYY-MM-DD)	Optional. Start date of patient birthdate range to filter patients by age.
PatientBirthdateTo	string (YYYY-MM-DD)	Optional. End date of patient birthdate range to filter patients by age.

Delete Patient Order

This function permanently deletes a patient order from the system. It requires both the institution UUID and the specific patient order UUID to ensure accuracy and prevent accidental deletion.

Required Parameters	Data Type	Description
UserName	string	The username (email address) for the PostDICOM account. (from initialization)
Password	string	The password associated with the PostDICOM account. (from initialization)
WebAddress	string	The base URL of the API. (from initialization)
PatientOrderInstitutionUuid	string	Required. UUID of the institution that owns the patient order. Ensures that the correct context is used for deletion.
PatientOrderUuid	string	Required. UUID of the specific patient order to be deleted. This uniquely identifies the order in the system.

Get Dicom Tag Content

Get DICOM Tag Content

This function retrieves the values of specific DICOM tags from the images associated with a patient order.

Required Parameters	Data Type	Description
UserName	string	The username (email address) for the PostDICOM account. (from initialization)
Password	string	The password associated with the PostDICOM account. (from initialization)
WebAddress	string	The base URL of the API. (from initialization)
PatientOrderInstitutionUuid	string	Required. The UUID of the institution where the order resides.
PatientOrderUuid	string	Required. The UUID of the order containing the images.
PatientSeriesUuid	string	Optional. If provided, tags will only be read from this specific series.
DicomTagIdList	List	Optional. A list of DICOM Tag IDs to retrieve.