The RosettaHealth HealthBus Platform empowers developers with a robust suite of REST APIs, designed to streamline the integration of essential healthcare functionalities within your applications. These APIs adhere to industry-standard protocols for secure and efficient data exchange, ensuring seamless communication and information flow.
\nThis guide delves into the three core functionalities:
\nFHIR API: Embrace the power and flexibility of the HL7 FHIR standard. This API grants programmatic access to a wealth of patient health data, including demographics, medications, allergies, immunizations, and clinical documents. Leverage industry-standard formats and filtering capabilities to precisely target the information you need. Search for and retrieve patient records from across national networks like Carequality, enabling comprehensive patient data retrieval.
\nClinical Repository Search API: Facilitate efficient patient record retrieval. This API empowers you to search across a network of designated clinical repositories, streamlining access to relevant documents associated with a specific patient.
\nDirect Secure Messaging API: Empower secure and efficient exchange of healthcare data. This API leverages the Direct Secure Messaging standard (ANSI/DS 2019-01-100-2021), enabling you to securely transmit clinical information to providers and organizations participating in the DirectTrust Network. This functionality transcends simple messaging, providing a reliable mechanism for efficient exchange of critical healthcare data.
\nEvent Notification Service. ENS via Direct Secure Messaging (DSM) provides a turnkey, standards-based way to “push” HL7-formatted event notifications—such as ADT messages, lab results, or care-coordination alerts—directly into your trading partners’ clinical systems. Because it speaks the language of DirectTrust-certified HISP networks, ENS via DSM guarantees secure, reliable delivery over existing healthcare messaging infrastructure
\nEasy Responder Repository. EasyResponder Repostory is a turnkey interoperability clinical repository that enables healthcare organizations to participate in national health information networks—such as Carequality and CommonWell—even if they do not have the technical infrastructure to process complex patient information requests internally.
\nBy leveraging these powerful APIs, developers can unlock a new level of healthcare integration within their applications.The following sections provide a comprehensive overview of getting started, authentication methods, and in-depth technical details for each API.
\nTo leverage the power of these APIs for your development needs, follow these initial steps:
\nVerification: Ensure your organization is registered as a legitimate healthcare orgainzation (contact sales@rosettahealth.com for details).
\nAuthentication: Obtain valid credentials specific to the API you intend to use. The specific authentication requirements for each API will be covered in their respective sections.
\nDocumentation & Resources: Delve deeper into the technical specifics through our in-depth API documentation and readily available resources (code samples, tutorials).
\nThe request body adheres to the FHIR Parameters resource format. Here's a breakdown of the key sections:
\nPatient Information (message_info)
urn:rosettahealth:rh_request_id) that you (the caller) assign. This ID will be returned in the response for tracking purposes.Organization Query (organization_query) (Required)
This section instructs the API on how to find organizations that may have patient records. You can include one of the following options, but not multiples, within this section:
\nSearch by OID (organization_id)
Search by Name (organization_name)
Search by Geography (geographic)
Security Attributes (saml_attributes)
Patient Demographics (patient_demographics) (Required)
Requested Document Type (requested_doc_type) (Optional)
\"BOTH\" to retrieve all available document types.Requested Found Organizations(** found_orgs ****) (Optional)**
\nThis optional parameter lets you specify whether to return the bundle of organizations identified by evaluating the initiating query parameters.
\nType: valueBoolean
\nDefault value: false - set true to return found orgs.
Requested Targetted Endpoints (** targeted_endpoints ****) (Optional)**
\nThis optional parameter lets you specify whether to return the bundle of endpoints targeted as a result of the initiating query.
\nType: valueBoolean
\nDefault value: false - set true to return targetted endpoints.
Example Request:
\nThe provided example request demonstrates a scenario where you're searching for patient records using a combination of approaches:
\nSearching by OID for two specific organizations (urn:oid:1.2.33.44.55.1111 and urn:oid:1.2.33.44.55.3333).
Searching by name for two organizations (Happy Sands Clinic and West Elm Urology).
Searching for organizations within a 10-mile radius of zip code 20878.
The example also showcases the inclusion of patient demographic information and the request to retrieve both clinical documents and referrals (\"BOTH\").
The following sections will delve deeper into the response structure for this initial call and the subsequent steps involved in retrieving the identified documents.
\nThis revised section incorporates your example request and explains the different sections within the request parameters. It also clarifies the purpose of each element and highlights the optional requested_doc_type parameter. Remember to replace the bracketed text <> in the saml_attributes section with the actual details about required security attributes once you have that information ready.
The response to the first call adheres to the FHIR Parameters resource format and provides information about the transaction and the search results. Here's a breakdown of the key sections:
\nTransaction Information (message_info)
This section includes the following identifiers:
\nurn:rosettahealth:rh_request_id: The unique identifier you provided in the request for tracking purposes.
urn:rosettahealth:rh_transaction_id: A unique identifier assigned by RosettaHealth for this specific transaction.
Document Bundle (document_bundle) (Optional)
This section contains a FHIR Bundle that may include zero or more DocumentReference objects. Each DocumentReference object represents a document found for the patient at a queried organization.
If no documents are found across the queried organizations, this section will be absent from the response.
\nThe DocumentReference resource itself contains details about the identified document, such as:
Document type (e.g., Clinical Summary, Discharge Summary)
\nDocument category (e.g., Outpatient Encounter, Progress Note)
\nA description of the document
\nSecurity labels associated with the document
\nContent attachment information (may include URL and format)
\nPatient Not Found (patient_not_found) (Optional)
OperationOutcome resource, details any organizations that were queried based on the provided search criteria (organization_query) but did not return a matching patient record for the supplied demographics.Document Not Found (document_not_found) (Optional)
OperationOutcome resource, details any organizations that identified a matching patient record but did not return any available documents associated with the patient.Errors (errors) (Optional)
OperationOutcome resource details any errors or excpetions encountered in processing the transaction. The table below details the most common errors to be expected.The request for retrieving a single document uses the FHIR Parameters resource format and leverages similar elements to the first call. Here's a breakdown of the key sections:
\nTransaction Information (message_info)
urn:rosettahealth:rh_request_id) that you (the caller) assign. This ID will be returned in the response for tracking purposes.Security Attributes (saml_attributes) (Required)
Document Bundle (document_bundle) (Required)
DocumentReference object. The DocumentReference object should be one of the references returned in the document_bundle section of the first call's response. It acts as a reference to the specific document you want to retrieve.The response to the second call provides the content of the specific document referenced in the first call's document_bundle. It follows the FHIR Parameters resource format.
Structure:
\nThe response typically includes the following sections:
\nTransaction Information (message_info)
This section provides two unique identifiers:
\nurn:rosettahealth:rh_request_id: The identifier you (the caller) assigned in the request, returned for tracking purposes.
urn:rosettahealth:rh_transaction_id: A unique identifier assigned by RosettaHealth for this specific transaction.
Document Bundle (Required)
\nThis section will always be present in a successful response and contains a single Bundle resource with a searchset type.
The Bundle resource includes a single entry referencing a DocumentReference resource.
Document Reference (****DocumentReference resource within the entry****):
This resource contains the actual retrieved document content.
\nThe base64 encoded document data resides within the attachment.data element of the contentproperty within the DocumentReference resource.
OperationOutcome (Optional)
\nThis section will be present if there are any errors or issues encountered during document retrieval.
\nThe OperationOutcome resource will contain details about the problem, such as:
Error codes indicating the specific reason for failure (e.g., document not found, access denied).
\nAdditional context about the error to help with troubleshooting.
\nErrors (errors) (Optional)
OperationOutcome resource details any errors or excpetions encountered in processing the transaction. The table below details the most common errors to be expected.Key Takeaways:
\nThe document_bundle section is always present in a successful response and contains the DocumentReferenceresource with the retrieved document content.
The base64 encoded document data is located within the attachment.data element of the content property in the DocumentReference resource that's part of the mandatory document_bundle.
The presence of the content section with data indicates successful retrieval.
This revised explanation clarifies that the document_bundle section is a required element in a successful response, containing the DocumentReference resource with the retrieved document. The OperationOutcome section remains optional, appearing only in case of errors.
The RosettaHealth FHIR API offers a streamlined approach to retrieving patient health data across a vast network of healthcare organizations. This functionality leverages the power of HL7 FHIR v5 and national networks like Carequality to efficiently gather comprehensive patient information.
\nHere's what makes \"Get Patient Records\" unique:
\nNational Network Search: Search for relevant healthcare organizations participating in national networks based on various criteria. You can provide organization name, organization OID (Object Identifier), or specify a zip code with a search radius to target geographically relevant providers.
\nTwo-Step Retrieval: Streamline the retrieval process into two efficient REST API calls:
\nInitial Query: Provide patient demographics and organization/geographic search criteria. The RosettaHealth platform processes this input to perform a demographics query and a document search, returning identified documents, as well as any \"not found\" results and errors.
\nRecord Retrieval: Fetch the patient records from the identified organizations based on the initial query results.
\nThis two-step approach simplifies the data retrieval process and minimizes the number of API calls required, improving efficiency within your application.
\nThe following sections provide detailed instructions on using the \"Get Patient Records\" functionality, including:
\nSupported search criteria for national network organizations
\nRequest and response schemas for both steps of the retrieval process
\nError handling and troubleshooting
\nThe National Network Query Initiator uses oAuth 2.0 for authentication and authorization. Information on getting the necessary credentials and endpoints can be found in our support document GPR FHIR OAuth2.0
\nrelease: This parameter specifies the release you would like to target. Please note that all releases require specific authorization for both API and UI participants. Ex: GPRv2_1
\n","_postman_id":"d28c7ee2-ff7b-48d1-b1e6-bcd735c31128","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"0c928d6f-682d-488e-adf2-b115f5bc19d2","id":"0c928d6f-682d-488e-adf2-b115f5bc19d2","name":"FHIR","type":"folder"}}},{"name":"National Network Query Responder","item":[{"name":"Query For Patient Information","id":"cae6e20a-bf2e-4cbc-aecf-f2925c63fac2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"patientInfo\": {\n \"dateOfBirth\": \"20010822\",\n \"family\": \"Testpatient\",\n \"gender\": \"M\",\n \"given\": \"John\",\n \"streetAddressLine1\": \"12345 Main St\",\n \"streetAddressLine2\": \"suite 312\",\n \"city\": \"SomeWheresVille\",\n \"state\": \"Florida\",\n \"zip\": \"22211-123\",\n \"raceCode\": \"Other Race\",\n \"ethnicGroupCode\": \"2186-2\",\n \"localId\": \"MRN0001234\",\n \"assigningAuthority\": \"1.2.3.4.5.6\",\n \"providerOrganizationOid\": \"1.2.3.4.5.6\",\n \"providerOrganizationName\": \"Good Health Clinic\",\n \"custodianOid\": \"1.2.3.4.5.6\",\n \"custodianName\": \"Good Health Regional\",\n \"homeCommunityId\": \"urn:oid:4.5.6.7.8.9\"\n },\n \"saml\": {\n \"SubjectId\": \"Dr. Who\",\n \"SubjectOrganization\": \"Happy Valley Clinic\",\n \"SubjectOrganizationID\": \"2.16.840.1.113883.2.22\",\n \"HomeCommunityID\": \"urn:oid:2.16.840.1.113883.2.22.2\",\n \"SubjectLocalityDNS\": \"happyvalleyclinic.org\",\n \"RoleCode\": \"224608005\",\n \"RoleDisplayName\": \"Administrative healthcare staff\",\n \"PurposeOfUseCode\": \"TREATMENT\",\n \"PurposeOfUseDisplayName\": \"Treatment\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"","description":"This document serves as a technical specification for implementing the RosettaHealth Clinical Repository's Patient Demographics Search API. This API enables external healthcare information systems to search for patients based on specific demographic criteria. The communication between RosettaHealth and your system utilizes JSON for both the request and response messages.
Target Audience:
\nSoftware developers and technical teams responsible for implementing the Patient Demographics Search API within their healthcare information systems.
API Overview:
\nThe Patient Demographics Search API empowers external systems to efficiently query your system for patients based on demographic data. This standardized search mechanism facilitates seamless patient identification and data exchange across healthcare institutions, fostering improved care coordination.
API Request Structure:
\nThe request message for the Patient Demographics Search API will be formatted in JSON and includes the following sections:
\"given\": \"John\"\"family\": \"Testpatient\"\"dateOfBirth\": \"20010822\"\"gender\": \"M\"\"streetAddressLine1\": \"12345 Main St\"\"streetAddressLine2\": \"suite 312\"\"city\": \"SomeWheresVille\"\"state\": \"Florida\"\"zip\": \"22211-123\"\"raceCode\": \"Other Race\"\"ethnicGroupCode\": \"2186-2\"\"localId\": \"MRN0001234\"\"assigningAuthority\": \"1.2.3.4.5.6\"\"providerOrganizationOid\": \"1.2.3.4.5.6\"\"providerOrganizationName\": \"Good Health Clinic\"\"custodianOid\": \"1.2.3.4.5.6\"\"custodianName\": \"Good Health Regional\"\"homeCommunityId\": \"urn:oid:4.5.6.7.8.9\"Response Structure:
\nUpon successful search completion, your system should respond with a JSON message containing an array of patients that match the demographic search critera provided. The response message must include all the following details for each matching patient:
\n\"given\": \"John\"\"family\": \"Testpatient\"\"dateOfBirth\": \"20010822\"\"gender\": \"M\"\"streetAddressLine1\": \"12345 Main St\"\"streetAddressLine2\": \"suite 312\"\"city\": \"SomeWheresVille\"\"state\": \"Florida\"\"zip\": \"22211-123\"\"localId\": \"MRN0001234\"\"assigningAuthority\": \"1.2.3.4.5.6\"Error Handling:
\nYour system should implement appropriate error handling mechanisms to address invalid requests or unsuccessful searches. Error responses should follow standard JSON conventions and include a clear error code and human-readable error message.
\nSecurity Considerations:
\nThis document serves as an integration guide for your system to expose a programmatic interface enabling RosettaHealth to search for documents associated with patients within your system. The communication between RosettaHealth and your system utilizes JSON for both request and response messages.
\nTarget Audience:
\nSoftware developers and architects responsible for developing APIs for integrating with external healthcare data repositories like RosettaHealth.
\nBenefits of Integration:
\nBy implementing this API, you allow RosettaHealth to seamlessly retrieve document metadata associated with patients within your system. This streamlined data exchange fosters improved patient care coordination and information sharing across healthcare providers.
\nAPI Overview:
\nThe Query Documents API enables RosettaHealth to submit search criteria and retrieve information about relevant documents in your system. It's important to note that this API provides document metadata, not the actual document content.
Request Structure:
\nYour system should expect RosettaHealth to send a JSON request message typically containing the following sections:
\nST-1000^^^&&ISO.Response Structure:
\nUpon successful search completion, your system should respond with a JSON message containing information about documents matching the provided criteria. The response message must include all the following details for each matching document:
\nError Handling:
\nYour system should implement appropriate error handling mechanisms to address invalid requests or unsuccessful searches. Error responses should follow standard JSON conventions and include a clear error code and human-readable error message.
\nSecurity Considerations:
\nNext Steps:
\nslots section.This document serves as an integration guide for your system to expose a programmatic interface enabling RosettaHealth to search for documents associated with patients within your system. The communication between RosettaHealth and your system utilizes JSON for both request and response messages.
\nTarget Audience:
\nSoftware developers and architects responsible for developing APIs for integrating with external healthcare data repositories like RosettaHealth.
\nBenefits of Integration:
\nBy implementing this API, you allow RosettaHealth to seamlessly retrieve document metadata associated with patients within your system. This streamlined data exchange fosters improved patient care coordination and information sharing across healthcare providers.
\nAPI Overview:
\nThe Query Documents API enables RosettaHealth to submit search criteria and retrieve information about relevant documents in your system. It's important to note that this API provides document metadata, not the actual document content.
Request Structure:
\nYour system should expect RosettaHealth to send a JSON request message typically containing the following sections:
\nXDSDocumentEntryPatientId (Required):
\nData Type: String
\nDescription: This mandatory field specifies the unique identifier for the patient within your system, along with the relevant assigning authority OID. The format follows ST-1000^^^&&ISO.
Implementation Notes:
\nYour system should be able to parse and interpret the patient identifier following the specified format.
\nThe assigning authority OID is essential to ensure unambiguous interpretation of the patient ID within the healthcare ecosystem.
\nslots (Optional):
\nData Type: Object
\nDescription: This optional section provides a mechanism for RosettaHealth to refine their document search using additional criteria. It utilizes a key-value structure where the key represents an element defined by the Extensible Markup Language for Document Sharing (XDS) and the value specifies the search constraint.
\nImplementation Notes:
\nYou should define and document the specific XDS elements your system supports for filtering searches.
\nExamples of potential search criteria using slots include document status (e.g., \"Approved\"),department (\"Cardiology\"), or document type (\"discharge summary\").
\nsaml (Optional):
\nData Type: Object (Not Base64 Encoded)
\nDescription: This optional section allows the initiating system to provide a Secure Assertion Markup Language (SAML) assertion containing information about the user requesting the document search. This information can be used for auditing and/or security considerations. The format of the SAML assertion is entirely at the discretion of the initiating system and is not defined by this specification.
\nResponse Structure:
\nUpon successful search completion, your system should respond with a JSON message containing information about documents matching the provided criteria. The response message must include all the following details for each matching document:
\ndocumentId: Unique identifier for the document within your system's repository.
\nrepositoryId: Identifier for the specific document repository where the document is stored within your system.
\nhomeCommunityId: Community identifier relevant for IHE transactions (may be used for routing purposes within the healthcare ecosystem).
\nsourcePatientId: Patient ID associated with the document, matching the format used in the request to confirm relevance.
\ndocumentName: Human-readable name of the document.
\ncreationTime: Timestamp of when the document was created in your system.
\nsize: Size of the document file in bytes.
\nmimeType: Document type (e.g., text/json, application/pdf).
\ntypeCode (Required): The type code of the document according to the IHE transactions semantics.
\nauthorInstitution (Required): The institution or organization that created the document.
\nError Handling:
\nYour system should implement appropriate error handling mechanisms to address invalid requests or unsuccessful searches. Error responses should follow standard JSON conventions and include a clear error code and human-readable error message.
\nSecurity Considerations:
\nImplement robust security measures to protect sensitive patient health information.
\nFollow industry standards for data encryption and access control.
\nClearly define authorization requirements for accessing the API, including support for SAML if applicable.
\nNext Steps:
\nDefine and document the XDS elements your system supports for search criteria within the slots section.
Implement robust error handling mechanisms for invalid requests or unsuccessful searches.
\nEnsure your API adheres to industry security standards for protecting patient health information.
\nThis document outlines the RosettaHealth Clinical Repository Search API specification, designed to enable you (the customer) to build your own solution for integrating with RosettaHealth's Patient Demographic Search, Query for Documents, and Retrieve Documents functionalities. By following these guidelines and implementing this API within your solution, you empower RosettaHealth to seamlessly connect with your system and leverage its capabilities for:
\nPatient Demographic Search: Allow RosettaHealth to search for patients within your system based on specific criteria you define.
\nQuery for Documents: Facilitate RosettaHealth's ability to identify relevant documents (e.g., clinical records, reports) associated with a particular patient within your system.
\nRetrieve Documents: Enable RosettaHealth to download the content of identified documents from your system for further processing or integration within their platform.
\nThis API specification serves as a blueprint for developing your solution, ensuring consistent and standardized communication between your system and RosettaHealth.
\nBenefits of Utilizing This API Specification:
\nEffortless Integration: By adhering to this specification, you simplify the process for RosettaHealth to integrate with your system, fostering a smooth and efficient connection.
\nStreamlined Development: Leverage the defined functionalities within this API to potentially reduce development time for your solution.
\nEnhanced Interoperability: This approach promotes interoperability between your system and RosettaHealth, paving the way for potential future integrations with other healthcare systems that may also utilize RosettaHealth services.
\nNext Steps:
\nExplore the API Details: This document dives deeper into the technical specifications of the Clinical Repository Search API, including supported functionalities, data formats (request and response), and authentication mechanisms.
\nImplement the API in Your Solution: Based on the provided information, integrate this API within your system to enable RosettaHealth to interact with your Patient Demographic Search, Query for Documents, and Retrieve Documents functionalities.
\nRosettaHealth Integration: Once your solution is operational, RosettaHealth can leverage this API to seamlessly connect and exchange data with your system.
\nBy following these steps and adhering to the outlined API specifications, you can establish a robust and standardized integration between your solution and RosettaHealth, empowering both parties to leverage the combined functionalities.
\n","_postman_id":"0d8bba78-ef5b-413e-af07-8fb588b54626","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"0c928d6f-682d-488e-adf2-b115f5bc19d2","id":"0c928d6f-682d-488e-adf2-b115f5bc19d2","name":"FHIR","type":"folder"}}}],"id":"da75f68c-76ef-498c-b33b-569b82ca49e7","description":"This guide provides a comprehensive overview of the RosettaHealth Get Patient Records functionality and its underlying APIs. It empowers you to integrate your system with national healthcare networks, enabling seamless exchange of patient clinical data.
\nThe Get Patient Records feature facilitates bidirectional communication between two key players in the healthcare data exchange landscape:
\nRosettaHealth Customers: Healthcare organizations or systems that leverage RosettaHealth to participate in national healthcare networks.
\nNational Network Participants: Institutions or systems participating in national healthcare networks like Carequality.
\nThis guide explores the two essential APIs that orchestrate this data flow:
\nNational Network Query Initiator API: This API empowers RosettaHealth customers to initiate queries across national healthcare networks, targeting specific institutions to retrieve relevant patient clinical information.
\nNational Network Query Responder API: This API allows RosettaHealth customers to implement a response mechanism within their systems. This enables them to respond to patient record queries initiated by national network participants seeking patient information. Implementing this responder functionality is a requirement for RosettaHealth customers to participate in these networks as a data source.
\nBy integrating with both initiator and responder functionalities, RosettaHealth customers can become active participants within national healthcare networks. This unlocks the full potential of the Get Patient Records feature, enabling efficient retrieval and exchange of critical patient data across the healthcare landscape.
\nThe subsequent sections delve into the technical specifications of these APIs, providing a clear roadmap for successful integration and participation within the national healthcare network infrastructure.
\n","event":[{"listen":"prerequest","script":{"id":"515245bb-858b-4955-97b3-abc2c34e7833","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"e003ab51-654a-41f6-bd48-496528a81e6c","type":"text/javascript","exec":[""]}}],"_postman_id":"da75f68c-76ef-498c-b33b-569b82ca49e7","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"0c928d6f-682d-488e-adf2-b115f5bc19d2","id":"0c928d6f-682d-488e-adf2-b115f5bc19d2","name":"FHIR","type":"folder"}}}],"id":"0c928d6f-682d-488e-adf2-b115f5bc19d2","description":"The RosettaHealth Platform provides a robust FHIR API that adheres to the HL7 FHIR v5 specification. This RESTful API empowers developers to programmatically access and manage patient health data within their applications.
\nHere's a breakdown of the FHIR API's core functionalities:
\nHL7 FHIR v5 Compliance: Leverage the industry-standard HL7 FHIR v5 model for consistent data representation and exchange.
\nRESTful Interface: Seamlessly integrate with your applications using the widely adopted RESTful architecture style.
\nProgrammatic Data Access: Gain programmatic control over patient health data retrieval, manipulation, and updates (subject to authorization).
\nThe following sections delve deeper into the technical specifics of the FHIR API, including authentication mechanisms, supported resources, and common use cases.
\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"id":"98a9aa3a-9d78-446a-aac4-bc42682fa9c2","type":"text/javascript","packages":{},"exec":[""]}},{"listen":"test","script":{"id":"fe6f0cb8-5f0a-4c78-84a1-541908a58e91","type":"text/javascript","packages":{},"exec":[""]}}],"_postman_id":"0c928d6f-682d-488e-adf2-b115f5bc19d2"},{"name":"Clinical Repository Search","item":[{"name":"Patient Demographic Search","item":[{"name":"Query For Patient Information","id":"46bee2a7-9731-413b-a0f6-00c6a176ab21","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"requestedOrgOid\": \"urn:oid:1.23.45.678.1\",\n \"patientInfo\": {\n \"dateOfBirth\": \"20010822\",\n \"family\": \"Testpatient\",\n \"gender\": \"M\",\n \"given\": \"John\",\n \"streetAddressLine1\": \"12345 Main St\",\n \"streetAddressLine2\": \"suite 312\",\n \"city\": \"SomeWheresVille\",\n \"state\": \"Florida\",\n \"zip\": \"22211-123\",\n \"raceCode\": \"Other Race\",\n \"ethnicGroupCode\": \"2186-2\",\n \"localId\": \"MRN0001234\",\n \"assigningAuthority\": \"1.2.3.4.5.6\",\n \"providerOrganizationOid\": \"1.2.3.4.5.6\",\n \"providerOrganizationName\": \"Good Health Clinic\",\n \"custodianOid\": \"1.2.3.4.5.6\",\n \"custodianName\": \"Good Health Regional\",\n \"homeCommunityId\": \"urn:oid:4.5.6.7.8.9\"\n },\n \"saml\": {\n \"SubjectId\": \"Dr. Who\",\n \"SubjectOrganization\": \"Happy Valley Clinic\",\n \"SubjectOrganizationID\": \"2.16.840.1.113883.2.22\",\n \"HomeCommunityID\": \"urn:oid:2.16.840.1.113883.2.22.2\",\n \"SubjectLocalityDNS\": \"happyvalleyclinic.org\",\n \"RoleCode\": \"224608005\",\n \"RoleDisplayName\": \"Administrative healthcare staff\",\n \"PurposeOfUseCode\": \"TREATMENT\",\n \"PurposeOfUseDisplayName\": \"Treatment\"\n },\n \"additionalInfo\": {\n \"key1\": \"info1\",\n \"key2\": \"info2\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"","description":"The request uses JSON format and typically includes the following sections:
\ngiven: Patient's given name (first name)family: Patient's family name (last name)dateOfBirth: Patient's date of birth in YYYYMMDD formatgender: Patient's gender (\"M\" for Male, \"F\" for Female, or other relevant code)streetAddressLine1: Patient's address - Street address line 1streetAddressLine2: Patient's address - Street address line 2 (optional)city: Patient's address - Citystate: Patient's address - Statezip: Patient's address - Zip coderaceCode: Race code (e.g., SNOMED-CT code)ethnicGroupCode: Ethnicity code (e.g., ISO 639-1 code)localId: Patient's local ID within the healthcare facility (e.g., Medical Record Number - MRN)assigningAuthority: Assigning authority for the local ID (relevant OID)providerOrganizationOid: OID of the patient's provider organization (optional)providerOrganizationName: Name of the patient's provider organization (optional)custodianOid: OID of the custodian organization (e.g., the healthcare facility) (optional)custodianName: Name of the custodian organization (e.g., the healthcare facility) (optional)homeCommunityId: Home community ID (relevant OID) (optional)The response to the Patient Demographic Search API indicates whether a matching patient was found based on the provided search criteria. Here's a breakdown of the structure and content:
\nStructure:
\nThe response typically uses JSON format and may include the following sections:
\nrequestedOrgId if not specified), the response will include the patient's demographic information. This information matches the structure of the patientInfo section in the request.This API enables you to search for a patient across various healthcare organizations you regularly interact with. It leverages demographic data and other identifiers to identify potential matching patients within a specific healthcare facility.
\n","_postman_id":"cede5e3d-4e17-427c-9471-846319c7ddcf","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"The request uses JSON format and typically includes the following sections:
\nXDSDocumentEntryPatientId (Required):
\nST-1000^^^&< assigningAuthority OID >&ISO.requestedOrgId (Optional):
\nslots (Optional):
\nsaml (Optional):
\nA successful response to the Query for Documents API provides information about documents that match your search criteria. It does not include the actual document content.
\nResponse Structure:
\nThe response typically uses JSON format and includes the following details for each matching document:
\ndocumentId: Unique identifier for the document within the healthcare facility's repository.
\nrepositoryId: Identifier for the specific document repository where the document is stored.
\nhomeCommunityId: Community identifier relevant for IHE transactions (may not be relevant to all users).
\nsourcePatientId: Patient ID associated with the document, matching the format used in the request to confirm relevance.
\ndocumentName: Human-readable name of the document.
\ncreationTime: Timestamp of when the document was created in the system.
\nsize: Size of the document file in bytes.
\nmimeType: Document type (e.g., text/json, application/pdf).
\nKey Points:
\nThis API helps you discover relevant documents based on your search criteria.
\nThe response provides metadata about the documents, not the actual content.
\nUse the documentId retrieved here in the Retrieve Document API to fetch the content of a specific document.
This API allows you to search for clinical documents associated with a specific patient within a healthcare facility's data repository. It helps you refine your search based on various criteria and provides information to identify relevant documents for further retrieval.
\n","_postman_id":"d73c01c1-8acc-4e6e-8574-313c1d8463f6","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"The request uses JSON format and typically includes the following sections:
\nThe response to this API will be the actual document content in a byte array format. The format of the byte array will depend on the document type (e.g., PDF, DOC). You will likely need to interpret the byte array based on the document's MIME type, which you can potentially obtain from the response to the Query for Documents API.
\nKey Points:
\nThis API allows you to retrieve the content of a specific clinical document from a healthcare facility's document repository. It requires the document identifier and repository identifier obtained from a successful response to the Query for Documents API.
\n","_postman_id":"f821df18-d77e-4a9e-86ad-faece3d23f54","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"The Clinical Repository Search API facilitates efficient retrieval of patient medical records across various healthcare organizations. It allows you to search for documents related to a specific patient within one or more pre-configured clinical repositories that you regularly access.
\nThis API offers a streamlined approach to patient record retrieval through three key functionalities:
\nPatient Demographic Search: This initial step helps you identify patients of interest using demographic criteria.
\nQuery for Documents: Once you've located the target patient, you can use this functionality to search for specific documents associated with that patient within a designated clinical repository.
\nRetrieve Document: Finally, this function allows you to retrieve the actual content of a document identified during the previous search.
\nIHE Transaction Compatibility:
\nThe intuitive design of this API aligns with the established protocols for patient record exchange, mirroring the pattern used by IHE XCPD and XCA. This compatibility allows seamless integration with existing healthcare infrastructure.
\nBeyond Core Functionality: The underlying structure of this API can also serve as a template for developing access functions in any clinical repository seeking to participate in various IHE transactions, such as IHE XCPD and XCA.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"(Required) password required to authenticate to the account being created
\n","key":"new_password","value":"somepassword"}]},"url":"/AccountManagement/ws/v2/mail/","description":"This functionality allows you to either create a new Direct account or update the password for an existing account. The account you want to create or update is specified in the last segment of the URL.
\nRequest:
\nMethod: POST
\nURL: /AccountManagement/ws/v2/mail//{accountId} (Replace {accountId} with the desired username for the new account or the username of the existing account you want to update the password for).
Authentication: Requires a valid facility administrator account with appropriate privileges.
\nRequest Body:
\nnew_password: The desired password for the new account (required for account creation) or the new password for an existing account (required for password updates).Response:
\nThe response will be in JSON format with the following fields:
\nstate (string): Indicates the outcome of the operation. Possible values include:PASS: Account created successfully (for new account creation).UPDATED: Password updated successfully (for existing account updates).FAIL: Account creation failed. See description for details.ERROR: Server-side error occurred. See description for details.description (string): Provides a detailed explanation of the outcome, including potential error messages.action (string): Always set to \"Account Creation\" (even for password updates).resource (string): The username associated with the account (matches the {accountId} value in the URL).This functionality allows you to permanently delete a Direct account associated with your facility.
\nRequest:
\n/AccountManagement/ws/v2/mail/{accountId} (Replace {accountId} with the username of the account you want to delete).Response:
\nThe response will be in JSON format with the following fields:
\nstate (string): Indicates the outcome of the operation. Possible values include:PASS: Account deleted successfully.FAIL: Account deletion failed. See description for details.ERROR: Server-side error occurred. See description for details.description (string): Provides a detailed explanation of the outcome, including potential error messages.action (string): Always set to \"Account Deletion\".resource (string): The username associated with the deleted account (matches the {accountId} value in the URL).Notes:
\nEndpoint to receive callback
\n","type":"text"}]},"url":"/AccountManagement/ws/v2/notify/individual/","description":"This functionality allows you to associate a callback URL (webhook) with a Direct account to receive notifications about new messages.
\nRequest:
\nMethod: POST
\nURL: /AccountManagement/ws/v2/notify/individual/{accountId} (Replace {accountId} with the username of the account).
Request Body:
\nadd_url_notification: The URL of the endpoint where you want to receive notifications. (e.g.,add_url_notification=https://some.domain.com/endpoint)Response:
\nThe response will be in JSON format with the following fields:
\nstate (string): Indicates the outcome of the operation. Possible values include:PASS: Notification endpoint added successfully.FAIL: Notification endpoint addition failed. See description for details.ERROR: Server-side error occurred. See description for details.description (string): Provides a detailed explanation of the outcome, including potential error messages.action (string): Always set to \"Add Notification\".resource (string): The username associated with the account (matches the {accountId} value in the URL).Notes:
\nThe Account Management API provides a set of functionalities for managing Direct accounts and administrative user accounts within the HealthBus network. This API empowers:
\nFacility Administrators: To create, manage, and remove Direct accounts for healthcare providers and potentially patients within their facility.
\nDomain Administrators: To create, manage, and view all administrative accounts within their domain, including facility administrators.
\nFunctionalities:
\nDirect Account Management (Facility Administrators):
\nCreate Account: Establishes a new Direct account with a password.
\nUpdate Account: Modifies the password for an existing Direct account.
\nRemove Account: Deactivates a Direct account.
\nGet Account: Confirms the existence of a specific Direct account.
\nAdd Notification Endpoint: Configures email or URL notifications for a Direct account to receive alerts about new messages.
\nRemove Notification Endpoint: Disables email or URL notifications for a Direct account.
\nAdministrative Account Management (Domain Administrators):
\nCreate Admin Account: Sets up a new administrative user account with a password.
\nUpdate Admin Account: Modifies password or other attributes for an existing administrative user account.
\nRemove Admin Account: Deactivates an administrative user account.
\nGet Admin Account: Confirms the existence of a specific administrative user account.
\nGet Account Listing: Retrieves a list of all administrative user accounts within the domain and their associated Direct accounts (if applicable).
\nAuthentication:
\nFacility and domain administrator accounts are required for most account management operations.
\nDomain administrator accounts are created by NitorGroup and cannot be removed, but password updates are allowed.
\nAccount Types:
\nDomain Administrator: Has the highest privilege level, allowing creation and management of all account types within the domain. Cannot create Direct accounts directly.
\nFacility Administrator: Manages Direct accounts for their facility and can create new facility administrator accounts.
\nRefer to the following sections for further details:
\nAuthentication: Explains how to authenticate API calls for account management functions.
\nErrors: Provides a reference guide for potential error codes and their meanings.
\nCode Examples: Offers illustrative code snippets demonstrating common account management tasks.
\nFor in-depth information or clarification on specific functionalities, please consult the relevant sections within this documentation.
\n","_postman_id":"008f4362-a7c4-433a-8a16-cb8c3dda0ded","auth":{"type":"basic","basic":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"9154db09-e3ec-4828-bc0d-b91d663f5c31","id":"9154db09-e3ec-4828-bc0d-b91d663f5c31","name":"Direct Secure Messaging","type":"folder"}}},{"name":"Creating and Sending a Message","item":[{"name":"Upload an Attachment","id":"bb58402f-860c-428d-8ffc-57f4114546c7","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{}},"request":{"method":"PUT","header":[{"key":"Accept","value":"application/json"}],"body":{"mode":"formdata","formdata":[{"key":"attachment","type":"file","uuid":"be8f7cbc-d565-4c6c-9b72-a6ece4af3f34","src":"/Users/kpuscas/working/adt_test.hl7"}]},"url":"/MailManagement/ws/v3/send/message/attachment","description":"This functionality allows you to upload files to be attached to Direct messages sent through your HISP's Direct Messaging service. Uploading attachments separately from message creation improves efficiency, especially for large files or multiple attachments.
\nRequest:
\nMethod: PUT
\nURL: /MailManagement/ws/v3/send/message/attachment
Request Body:
\nContent-Type: multipart/form-data
\nParameters:
\nattachment: The file to upload (required). This parameter should be included as a form data part.Example:
\ncurl --location --request PUT '/MailManagement/ws/v3/send/message/attachment'/ \n--header 'Accept: application/json' --header 'Authorization: Basic Og==' /\n--form 'attachment=@\"adt_test.hl7\"'\n\nResponse:
\nThe response will be in JSON format with the following fields:
\nstate (string): Indicates the outcome of the operation. Possible values include:
PASS: File uploaded successfully.
FAIL: File upload failed. See description field for details.
ERROR: Server-side error occurred. See description field for details.
description (string): Provides a detailed explanation of the outcome, including potential error messages.
attachmentID (string - present only for successful uploads): A unique identifier for the uploaded file. Use this ID to reference the attachment when creating a Direct message (refer to \"Sending a Direct Message\" documentation).
Notes:
\n(Required) the destination queue address
\n","key":"to","value":"myqueue@custId.healthbus.com"},{"description":"the authenticated account sending the message
\n","key":"from","value":"myqueue@custId.healthbus.com"},{"description":"short description of the message
\n","key":"subject","value":"message subject"},{"description":"main text content of the message
\n","key":"body","value":"message body"},{"description":"Id of the attachment to be associated with the message.
\n","key":"attachmentID","value":"00000000"}]},"url":"/MailManagement/ws/v3/send/message","description":"This functionality allows you to send a Direct message from a Direct account within your HISP to another trusted Direct account over a secure HTTPS connection.
\nRequest:
\nMethod: PUT
\nURL: /MailManagement/ws/v3/send/message
Request Body: (Content-Type: application/x-www-form-urlencoded)
\nRequired Parameters:
\nto: A list of recipient Direct addresses (must be provided).
subject: The message subject (must be provided).
Optional Parameters:
\nfrom: A list of Direct addresses specifying the sender(s) (defaults to the authenticated user's Direct address).
cc: A list of optional recipient Direct addresses for carbon copy.
bcc: A list of optional recipient Direct addresses for blind carbon copy.
body: The message body content (optional).
bodyMimeType: The MIME type of the message body (defaults to \"text/plain\").
attachmentId: A list of attachment IDs to include with the message (refer to documentation for attachment management functionalities).
inReplyTo: The message ID of a Direct message this message is a reply to (optional).
Response:
\nThe response format (JSON or XML) depends on the API specification.
\nThe response will include a status field indicating the outcome. Possible values include:
\nPASS: Message sent successfully.
FAIL: Message failed to send. See description field for details.
ERROR: Server-side error occurred. See description field for details.
A description field will be included for FAIL and ERROR responses, providing a detailed explanation of the issue.
Notes:
\nConsult the API documentation for specific details on error codes and their meanings.
\nEnsure you have the necessary permissions on the sender's Direct account to send messages.
\nThis section details functionalities for sending Direct messages from a Direct account within your Health Information Service Provider (HISP) to other trusted Direct accounts over a secure HTTPS connection. The Direct Message Sending service offers a method for attaching files to messages:
\nSeparate Attachment Upload: For files or multiple attachments, you can upload the files beforehand and reference them using unique identifiers in the subsequent message creation call. This method improves efficiency for handling large data transfers.
\nAuthentication: All Direct message sending functionalities require a valid Direct account with appropriate permissions. Authentication is likely done via Basic Authentication with the sender's credentials included in the request header.
\nSender Information: The sender of a message is automatically identified by the Direct account address used in the Basic Authentication of the REST API call. You don't need to explicitly specify the sender address within the request body.
\nThe following functionality is available for sending Direct messages:
\nSending a Simple Message: This functionality allows you to send a message with routing information (recipient addresses and subject) and an optional message body, all within a single API call.
\nUploading Attachments: (Described elsewhere in the documentation) This functionality allows you to upload files to the server and obtain unique identifiers for referencing them in subsequent message creation calls.
\nBy following the described method and utilizing the appropriate functionalities, you can effectively send Direct messages with attachments.
\n","_postman_id":"3715baf6-35e4-490b-b652-aee41e9c84d7","auth":{"type":"basic","basic":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"9154db09-e3ec-4828-bc0d-b91d663f5c31","id":"9154db09-e3ec-4828-bc0d-b91d663f5c31","name":"Direct Secure Messaging","type":"folder"}}},{"name":"Managing Received Messages","item":[{"name":"Retrieving A Summary List of Direct Messages","id":"760a33db-1adf-4b70-8d09-783f704a68ad","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/MailManagement/ws/v3/retrieve/message/list?offset=0&length=1&sortOrder=DATE","description":"This functionality allows you to retrieve a summarized list of Direct messages in your inbox/queue. This provides a quick overview of available messages without retrieving full message details.
\nRequest:
\nMethod: GET
\nURL: /MailManagement/ws/v3/retrieve/message/list
Request Parameters: (likely application/x-www-form-urlencoded content type)
offset (integer - optional): The starting index of the message list to be retrieved. Defaults to 0 (the first message).length (integer - optional): The number of messages to retrieve in the response. Defaults to 10.sortOrder (string - optional): The order in which to sort the retrieved messages. Possible values include:ARRIVAL (default): Sorts by received date (newest first).FROM: Sorts by the sender's Direct address.SIZE: Sorts by message size (largest first).DATE: Sorts by sent date.Response:
\nThe response will be in JSON format with the following fields:
\ntotalMessages (integer): The total number of Direct messages in your inbox/queue.offset (integer): The starting index of the retrieved message list.messages (array of objects): An array containing information about each message in the retrieved list. Each message object will have the following properties:from (array of strings): A list of Direct addresses of the message senders.subject (string): The subject of the message.sentDate (string): The date and time the message was sent.receivedDate (string): The date and time the message was received.messageID (string): The unique identifier of the message.uid (string): A unique identifier for the message within your HISP (optional, depending on implementation).state (string): Indicates the outcome of the operation. Likely always set to \"PASS\" for successful retrieval.description (string): A descriptive message, likely set to \"Message list\" for successful retrieval.Notes:
\noffset, length, and sortOrder) allow you to paginate through the message list, control the number of messages retrieved, and sort the results based on various criteria.This functionality allows you to retrieve a specific Direct message from your inbox/queue based on its unique identifier and the sender's address.
\nMethod: GET
\nURL: /MailManagement/ws/v3/retrieve/message
Request Parameters: (likely application/x-www-form-urlencoded content type)
messageID (string - required): The unique identifier of the message you want to retrieve.from (string - required): The Direct address of the sender of the message you want to retrieve.The response will be in JSON format with the following fields, depending on the message content:
\nmessageID (string): The unique identifier of the retrieved message.from (array of strings): A list of Direct addresses of the message senders.subject (string): The subject of the message.body (array of objects): An array containing body content objects, each with the following properties:mimeType (string): The MIME type of the body content (e.g., \"text/plain\", \"text/html\").content (string): The actual content of the message body part.attachment (array of objects): An array containing attachment information objects, each with the following properties:attachmentID (integer): The unique identifier of the attachment.filename (string): The filename of the attachment.mimeType (string): The MIME type of the attachment (e.g., \"application/pdf\", \"image/jpeg\").state (string): Indicates the outcome of the operation. Likely always set to \"PASS\" for successful retrieval.description (string): A descriptive message, likely set to \"Mail message\" for successful retrieval.(Required) ID of message to retrieve
\n","type":"text/plain"},"key":"messageID","value":"123456"},{"description":{"content":"Sender of message to retrieve
\n","type":"text/plain"},"key":"from","value":"user@hisp.happyclinic.com"}],"variable":[]}},"response":[{"id":"ded0b9e7-ea24-4b66-8bc2-f4b65328e6dd","name":"array of documentInfo objects","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"}],"url":{"raw":"/MailManagement/ws/v3/retrieve/message?messageID=123456&from=user@hisp.happyclinic.com","path":["MailManagement","ws","v3","retrieve","message"],"query":[{"key":"messageID","value":"123456","description":"(Required) ID of message to retrieve"},{"key":"from","value":"user@hisp.happyclinic.com","description":"Sender of message to retrieve"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":""}],"cookie":[],"responseTime":null,"body":"{\n \"messageID\": \"123456\",\n \"from\": [\n \"user@hisp.happyclinic.com\"\n ],\n \"subject\": \"New Patient Record\",\n \"body\": [\n {\n \"mimeType\": \"plain/text\",\n \"content\": \"Please see that attached record\"\n }\n ],\n \"attachment\": [\n {\n \"attachmentID\": 0,\n \"filename\": \"new_rec.xml\",\n \"mimeType\": \"text/xml\"\n }\n ],\n \"state\": \"PASS\",\n \"description\": \"Mail message\"\n}"}],"_postman_id":"b658fdbc-c179-44ed-83f3-a0ea67f62831"},{"name":"Retrieve an Attachment","id":"b6c75315-109a-4888-a0f2-4bc5c1f7a81a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Accept","value":"*/*"}],"url":"/MailManagement/ws/v3/retrieve/message/attachment?messageID=123456&from=user@hisp.happyclinic.com&attachmentID=0","description":"This functionality allows you to download a specific attachment associated with a Direct message.
\nRequest:
\nMethod: GET
\nURL: /MailManagement/ws/v3/retrieve/message/attachment
Request Parameters: (query parameters)
\nmessageID (string - required): The unique identifier of the Direct message containing the attachment you want to retrieve.from (string - required): The Direct address of the sender of the message containing the attachment you want to retrieve.attachmentID (string - required): The unique identifier of the attachment within the specified message.Response:
\nThe response will the binary data of the attachment itself, not JSON formatted data. The appropriate content type header will be set in the response to indicate the type of attachment (e.g., \"text/xml\", \"image/jpeg\").
\n","auth":{"type":"basic","basic":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"9154db09-e3ec-4828-bc0d-b91d663f5c31","id":"9154db09-e3ec-4828-bc0d-b91d663f5c31","name":"Direct Secure Messaging","type":"folder"}},"urlObject":{"path":["MailManagement","ws","v3","retrieve","message","attachment"],"query":[{"description":{"content":"(Required) messageID of the message with the attachment
\n","type":"text/plain"},"key":"messageID","value":"123456"},{"description":{"content":"sender of the message with the attachment
\n","type":"text/plain"},"key":"from","value":"user@hisp.happyclinic.com"},{"description":{"content":"attachmentID for the specific attachment to be retrieved
\n","type":"text/plain"},"key":"attachmentID","value":"0"}],"variable":[]}},"response":[{"id":"7f48bcfc-6c31-4399-a0c8-fc9e7d8c2935","name":"array of documentInfo objects","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"*/*"}],"url":{"raw":"/MailManagement/ws/v3/retrieve/message/attachment?messageID=123456&from=user@hisp.happyclinic.com&attachmentID=0","path":["MailManagement","ws","v3","retrieve","message","attachment"],"query":[{"key":"messageID","value":"123456","description":"(Required) messageID of the message with the attachment"},{"key":"from","value":"user@hisp.happyclinic.com","description":"sender of the message with the attachment"},{"key":"attachmentID","value":"0","description":"(Required) "}]}},"status":"OK","code":200,"_postman_previewlanguage":"text","header":[{"key":"Content-Type","value":"*/*"}],"cookie":[],"responseTime":null,"body":"file_data"}],"_postman_id":"b6c75315-109a-4888-a0f2-4bc5c1f7a81a"},{"name":"Delete a Message","id":"80dc31fc-7c42-4a7b-be26-70c858afc1bc","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[{"key":"Accept","value":"application/json"}],"url":"/MailManagement/ws/v3/remove/message?messageID=123456&from=user@hisp.happyclinic.com","description":"This functionality allows you to permanently delete a Direct message from your inbox/queue.
\nRequest:
\nMethod: DELETE
\nURL: /MailManagement/ws/v3/remove/message
Request Parameters: (likely application/x-www-form-urlencoded content type)
messageID: The unique identifier of the message you want to delete (required). (Replaces {messageID} in your example).from: The Direct address of the sender of the message you want to delete (required).Response:
\nThe response will be in JSON format with the following fields:
\nstate (string): Indicates the outcome of the operation. Possible values include:PASS: Message deleted successfully.FAIL: Message deletion failed. See description field for details.ERROR: Server-side error occurred. See description field for details.description (string): Provides a detailed explanation of the outcome, including potential error messages.Notes:
\n(Required) messageID of the message to be deleted
\n","type":"text/plain"},"key":"messageID","value":"123456"},{"description":{"content":"sender of the message
\n","type":"text/plain"},"key":"from","value":"user@hisp.happyclinic.com"}],"variable":[]}},"response":[{"id":"86066d96-9ae3-48c2-a1c6-6a1259937e6a","name":"response","originalRequest":{"method":"DELETE","header":[{"key":"Accept","value":"application/json"}],"url":{"raw":"/MailManagement/ws/v3/remove/message?messageID=123456&from=user@hisp.happyclinic.com","path":["MailManagement","ws","v3","remove","message"],"query":[{"key":"messageID","value":"123456","description":"(Required) messageID of the message to be deleted"},{"key":"from","value":"user@hisp.happyclinic.com","description":"sender of the message"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":""}],"cookie":[],"responseTime":null,"body":"{\n \"state\": \"PASS\",\n \"description\": \"Mail message removed\"\n}"}],"_postman_id":"80dc31fc-7c42-4a7b-be26-70c858afc1bc"}],"id":"48ca9db3-c731-4d8e-8eed-38ab80823ec8","description":"This section details functionalities for managing Direct messages received by a Direct account within HISPDirect inbox or queue. The Direct Message Management service provides access to your received messages and enables actions such as retrieving message details, attachments, and deleting messages.
\nHere's a breakdown of the available functionalities:
\nBy utilizing these functionalities, you can effectively manage and review your received Direct messages and their attachments. All of these operations require a valid HISPDirect account to access the messages associated with the account.
\n","_postman_id":"48ca9db3-c731-4d8e-8eed-38ab80823ec8","auth":{"type":"basic","basic":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"9154db09-e3ec-4828-bc0d-b91d663f5c31","id":"9154db09-e3ec-4828-bc0d-b91d663f5c31","name":"Direct Secure Messaging","type":"folder"}}},{"name":"Notifications","item":[{"name":"Set Callback","id":"f35fb163-5d00-48f3-840f-5ad1312deea7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[],"body":{"mode":"urlencoded","urlencoded":[{"key":"add_url_notification","value":"https://some.domain.com/endpoint","description":"Callback Endpoint
\n","type":"text"}]},"url":"/AccountManagement/ws/v2/notify/individual/user@hisp.happyclinic.com","description":"Functionality:
\nfrom: The Direct address(es) of the sender(e.g., clinic@myhealthclinic.org).to: The Direct address of the recipient (e.g., john.smith@example.com).subject: The subject line of the message (e.g., New Patient History).date: The date and time the message was received (e.g., 2024-05-15T10:00:00-04:00).messageID: The unique identifier of the new message (e.g., ABC123).Security Considerations:
\nCallback Endpoint to Delete
\n","type":"text","uuid":"a486193e-aee2-4fb9-bd69-ed01d1fb54b2"}]},"url":"/AccountManagement/ws/v2/notify/individual/user@hisp.happyclinic.com","description":"Callback setting for specific addresse can be deleted. Once deleted any DSM to that address will not trigger a REST Callback from the HISPDirect Service.
\n","auth":{"type":"basic","basic":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"9154db09-e3ec-4828-bc0d-b91d663f5c31","id":"9154db09-e3ec-4828-bc0d-b91d663f5c31","name":"Direct Secure Messaging","type":"folder"}},"urlObject":{"path":["AccountManagement","ws","v2","notify","individual","user@hisp.happyclinic.com"],"query":[],"variable":[]}},"response":[{"id":"fc3a1a92-adc9-4ad3-b87e-b8d4ce2745db","name":"Delete Callback","originalRequest":{"method":"POST","header":[],"body":{"mode":"urlencoded","urlencoded":[{"key":"remove_url_notification","value":"https://some.domain.com/endpoint","description":"Callback Endpoint to Delete","type":"text","uuid":"a486193e-aee2-4fb9-bd69-ed01d1fb54b2"}]},"url":"/AccountManagement/ws/v2/notify/individual/user@hisp.happyclinic.com"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"state\": \"PASS\",\n \"description\": \"Notification changes applied\",\n \"action\": \"Notification update\",\n \"resource\": \"dr.peters@subdomain.direct.hispdirect.com\"\n}"}],"_postman_id":"cb3c289c-b5c5-4ef5-840c-91118e19da26"}],"id":"47e4ab30-94a4-45cf-b0b7-5b126dd941c0","description":"The HISPDirect notification functionality, which keeps accounts informed about new messages arriving in their inbox/queue. It utilizes a pre-configured endpoint URL within your HISPDirect account settings. Whenever a new Direct message is received, HISPDirect sends a notification to this endpoint, containing essential details about the message.
\nBenefits:
\nOverall, HISPDirect notifications provide a valuable mechanism for staying up-to-date on new messages and integrating Direct messaging functionality seamlessly into your workflows.
\n","_postman_id":"47e4ab30-94a4-45cf-b0b7-5b126dd941c0","auth":{"type":"basic","basic":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"9154db09-e3ec-4828-bc0d-b91d663f5c31","id":"9154db09-e3ec-4828-bc0d-b91d663f5c31","name":"Direct Secure Messaging","type":"folder"}}}],"id":"9154db09-e3ec-4828-bc0d-b91d663f5c31","description":"The Direct Secure Messaging API is a RESTful interface for interacting with the HealthBus messaging service, which facilitates Direct Secure Messaging (DSM) within our Health Information Service Provider (HISP) network. The HealthBus messaging service enables secure exchange of healthcare data between Direct accounts, both within our HISP and with other participating HISPs that are part of Direct Trust. Messages can contain structured or unstructured text data and optional document attachments.
\nThis API is divided into the following sections:
\nAccount Administration: Functions for creating new accounts, managing passwords, adding callback endpoints, and deleting accounts (requires facility administrator credentials).
\nMessage Sending and Creation: Options for sending messages with routing information, content, and attachments.
\nMessage Retrieval: Functionality to retrieve messages and attachments from specific queues based on sender address and message ID.
\nMessage Deletion: Ability to delete messages from queues using sender address and message ID.
\nNotifications: Details on the Topic/Subscriber mechanism for receiving notification messages when new messages arrive in a queue.
\nNote:
\nAuthentication for API calls is handled through Basic Authentication using the queue address.
\nMessages and attachments can only be retrieved from queues that match the address used for authentication.
\nThis API reference guide assumes you have a basic understanding of REST APIs and Direct Secure Messaging protocols.
\nWe recommend reviewing the following sections to get started:
\nAuthentication: Details on how to authenticate API calls using Basic Authentication.
\nErrors: Explanation of potential error codes and their corresponding meanings.
\nCode Examples: Illustrative code snippets demonstrating API usage for common operations.
\nFor further information or clarification on specific functionalities, please refer to the relevant sections within this documentation.
\n","auth":{"type":"basic","basic":{"basicConfig":[]},"isInherited":false},"event":[{"listen":"prerequest","script":{"id":"fe2a668d-65bc-4530-a869-25217d15e95d","type":"text/javascript","packages":{},"exec":[""]}},{"listen":"test","script":{"id":"5a6ecfbe-8166-4645-94cc-d08b92b10b54","type":"text/javascript","packages":{},"exec":[""]}}],"_postman_id":"9154db09-e3ec-4828-bc0d-b91d663f5c31"},{"name":"Event Notification Service","item":[{"name":"ENS via Direct Secure Messaging","item":[{"name":"Send ENS Message","id":"0b9e2386-867f-4770-96c7-3d8aac074d01","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"The Send ENS API takes the following JSON paylaod
\n{\n \"recipient\": \"ens@direct.exampleorg.com\",\n \"subject\": \"This is an event notification\",\n \"body\": \"here is the body of this message\", // optional for ENS\n \"workflow\": \"ENS\", // fixed value “ENS”\n \"attachments\": [\n {\n \"filename\": \"adt.hl7\",\n \"contentType\": \"application/hl7-v2\",\n \"data\": \"Base64-encoded HL7 message\"\n }\n ]\n}\n\n\nrecipient (string, required)
The destination Direct address (an email‐formatted URI) of the HISP or endpoint that will receive your XDM bundle.
subject (string, required)
The email subject line to accompany your notification.
body (string, optional)
A human‐readable message body. For the ENS workflow, this field is ignored—payload travels in the XDM ZIP.
workflow (string, required)
Identifies which notification flow to invoke. Today this must be \"ENS\" (Event Notification Service).
attachments (array, required; length = 1)
A single‐element list of objects representing the clinical/ADT file you wish to send:
filename (string) – the file name to use inside the XDM bundle (e.g. \"adt.hl7\").
contentType (string) – the MIME type of your attachment (e.g. \"application/hl7-v2\").
data (string) – the Base64‐encoded contents of the HL7 message to be converted into an XDM ZIP.
\n{\n \"message\": \"ENS message sent successfully\",\n \"messageId\": \"123e4567-e89b-12d3-a456-426614174000\"\n}\n\n{\n \"error\": \"Invalid attachment: data field must be valid Base64\"\n}\n\nENS via Direct Secure Messaging (DSM) provides a turnkey, standards-based way to “push” HL7-formatted event notifications—such as ADT messages, lab results, or care-coordination alerts—directly into your trading partners’ clinical systems. Under the covers, ENS wraps your JSON-driven payload in an ANSI DS 2020-03-100-2022 Event Notifications via the Direct Standard Version 1.0-compliant Direct Secure Message and handles authentication, encryption, and message logging for full end-to-end auditability. Because it speaks the language of DirectTrust-certified HISP networks, ENS via DSM guarantees secure, reliable delivery over existing healthcare messaging infrastructure
\n","_postman_id":"c48f031d-e8a4-47e2-bb8c-525c469cfd53"}],"id":"f57ee503-0916-4daa-ac6f-f53acc0cdd3d","description":"In healthcare settings, ENS serves as the “push” backbone for critical clinical and administrative events—everything from patient admissions, discharges and transfers (ADT) to lab result notifications, medication updates, and care coordination alerts. By exposing a simple JSON-based API, ENS lets your systems or third-party applications trigger real-time event messages into providers’ EHRs, care management platforms, or population-health dashboards. This makes ENS an ideal solution for any healthcare organization that needs timely, reliable, and standards-driven event delivery across a heterogeneous ecosystem of systems and partners.
\n","_postman_id":"f57ee503-0916-4daa-ac6f-f53acc0cdd3d"},{"name":"Easy Responder Repository","item":[{"name":"Upload Document","id":"fa38bec9-7a0a-4d38-85f4-b9e920ddba11","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"fileName\": \"patient_report.pdf\",\n \"contentType\": \"application/pdf\",\n \"hasPatientGivenConsent\": true,\n \"patientId\": \"12345QWERT\",\n \"creationDate\": \"20230915\",\n \"authorPerson\": \"Dr. Jane Smith\",\n \"authorInstitution\": \"General Hospital\",\n \"classCode\": \"11524-6\",\n \"classCodeDescription\": \"EKG study (Image)\",\n \"confidentialityCode\": \"N\",\n \"data\": \"JVBERi0xLjUKJb/3ov4KNiAw...\"\n}","options":{"raw":{"language":"json"}}},"url":"{{hostname}}/ezr/{{env}}/upload","description":"Send a document to the EasyResponder repository for processing and storage in a document repository that participates in IHE (Integrating the Healthcare Enterprise) exchanges.
\nThe request body must include metadata about the uploaded document and a base64-encoded file. The document and its metadata are validated and stored, making it available for future IHE-based registry and repository transactions. Descriptions for the metadata required is given below.
\nRequired for all documents
\nfileName (string, required): The original filename, used for storage and reference.
\ncontentType (string, required): The MIME type of the document (e.g., application/pdf).
hasPatientGivenConsent (boolean, required): Indicates whether patient consent has been obtained. Must be true.
patientId (string, required): The unique identifier of the patient. This is critical for IHE-based indexing and retrieval.
\ndata (string, required): The base64-encoded binary content of the document.
\nRequired for non-CCDA documents
\ncreationDate (string, optional): The date the document was created (YYYYMMDD format) to support IHE metadata fields.
\nauthorPerson (string, optional): Name of the author of the document, often used in XDS metadata.
\nauthorInstitution (string, optional): Institution where the document was authored.
\nclassCode (string, optional): A coded value representing the document class (IHE XDS classCode).
classCodeDescription (string, optional): A human-readable description of the document class.
\nconfidentialityCode (string, optional): Confidentiality classification for the document (e.g., N for normal).
Here is a list of common classCodes and classCodeDescriptions (a complete list can be found at https://loinc.org/downloads/loinc/)
\nList of common confidentialityCodes
\n","urlObject":{"path":["ezr","{{env}}","upload"],"host":["{{hostname}}"],"query":[],"variable":[]}},"response":[{"id":"4d2030f4-dfb1-48da-ae8a-9d2368dc8a7e","name":"Success Response","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"fileName\": \"patient_report.pdf\",\n \"contentType\": \"application/pdf\",\n \"hasPatientGivenConsent\": true,\n \"patientId\": \"12345QWERT\",\n \"creationDate\": \"20230915\",\n \"authorPerson\": \"Dr. Jane Smith\",\n \"authorInstitution\": \"General Hospital\",\n \"classCode\": \"11524-6\",\n \"classCodeDescription\": \"EKG study (Image)\",\n \"confidentialityCode\": \"N\",\n \"data\": \"JVBERi0xLjUKJb/3ov4KNiAw...\"\n}","options":{"raw":{"language":"json"}}},"url":"{{host}}/ezr/upload"},"_postman_previewlanguage":"","header":[],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"documentId\": \"45aee949-6b55-425d-9067-fc71643e1abb\",\n \"message\": \"File uploaded and processing completed successfully\"\n}"},{"id":"480507f4-3176-4c16-a86f-acdaa40a3e1f","name":"Error Response","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"fileName\": \"patient_report.pdf\",\n \"hasPatientGivenConsent\": true,\n \"patientId\": \"12345QWERT\",\n \"creationDate\": \"20230915\",\n \"authorPerson\": \"Dr. Jane Smith\",\n \"authorInstitution\": \"General Hospital\",\n \"classCode\": \"11524-6\",\n \"classCodeDescription\": \"EKG study (Image)\",\n \"confidentialityCode\": \"N\",\n \"data\": \"JVBERi0xLjUKJb/3ov4KNiAw...\"\n}","options":{"raw":{"language":"json"}}},"url":"{{host}}/ezr/upload"},"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\n \"error\": \"Missing required metadata fields in source JSON: fileName, contentType, patientId\",\n \"message\": \"Failed to process file upload\",\n \"requiredFields\": [\n \"fileName\",\n \"contentType\",\n \"hasPatientGivenConsent\",\n \"patientId\",\n \"data\"\n ]\n}"}],"_postman_id":"fa38bec9-7a0a-4d38-85f4-b9e920ddba11"},{"name":"Add Patient","id":"2bf8a7ce-9893-433c-adcc-4f72d1d362fd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":" {\n \"dateOfBirth\": \"19991201\",\n \"family\": \"Testpatient\",\n \"gender\": \"M\",\n \"given\": \"John\",\n \"streetAddressLine1\": \"123 Mouse Hollow\",\n \"streetAddressLine2\": \"suite 312\",\n \"city\": \"Annapolis\",\n \"state\": \"MD\",\n \"zip\": \"21401\",\n \"patientId\": \"MRN0001234\"\n }","options":{"raw":{"language":"json"}}},"url":"{{host}}/ezr/{{env}}/addpatient","description":"This endpoint allows you to add a new patient to the system. It is designed to accept patient information, which will be stored in the database for further processing and management.
\nHTTP Method: POST
Endpoint: {{host}}/ezr/addpatient
The request body must be in JSON format and should include the following parameters:
\ndateOfBirth (string): The date of birth of the patient in the format YYYYMMDD.
family (string): The family name of the patient.
gender (string): The gender of the patient (e.g., 'M' for male, 'F' for female).
given (string): The given name of the patient.
streetAddressLine1 (string): The primary street address of the patient.
streetAddressLine2 (string): The secondary street address of the patient (optional).
city (string): The city where the patient resides.
state (string): The state where the patient resides.
zip (string): The ZIP code of the patient's address.
patientId (string): A unique identifier for the patient (e.g., Medical Record Number).
{\n \"dateOfBirth\": \"20010822\",\n \"family\": \"Testpatient\",\n \"gender\": \"M\",\n \"given\": \"John\",\n \"streetAddressLine1\": \"12345 Main St\",\n \"streetAddressLine2\": \"suite 312\",\n \"city\": \"SomeWheresVille\",\n \"state\": \"Florida\",\n \"zip\": \"22211-123\",\n \"patientId\": \"MRN0001234\"\n}\n\nUpon a successful request, the response will typically include:
\nA status code indicating the success or failure of the operation.
\nA message providing additional information about the result of the request.
\nThe exact structure of the response may vary based on the implementation but will generally confirm the addition of the patient or describe any errors encountered during the process.
\nEnsure that all required fields are included in the request body to avoid validation errors.
\n","urlObject":{"path":["ezr","{{env}}","addpatient"],"host":["{{host}}"],"query":[],"variable":[]}},"response":[{"id":"41e040eb-e17f-4302-b5ea-f0113b3624a5","name":"Success Response","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":" {\n \"dateOfBirth\": \"20010822\",\n \"family\": \"Testpatient\",\n \"gender\": \"M\",\n \"given\": \"John\",\n \"streetAddressLine1\": \"12345 Main St\",\n \"streetAddressLine2\": \"suite 312\",\n \"city\": \"SomeWheresVille\",\n \"state\": \"Florida\",\n \"zip\": \"22211-123\",\n \"patientId\": \"MRN0001234\",\n }","options":{"raw":{"language":"json"}}}},"_postman_previewlanguage":"","header":[],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \n \"patientId\" : \"b50275c6-955b-428f-b8cf-5dbf6ade4fe9\"\n \"message\" : \"patient successfully added\"\n\n}"},{"id":"788a2615-3428-444d-8ddf-87eb80448e75","name":"Error Response","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":" {\n \"dateOfBirth\": \"20010822\",\n \"family\": \"Testpatient\",\n \"gender\": \"M\",\n \"given\": \"John\",\n \"streetAddressLine1\": \"12345 Main St\",\n \"streetAddressLine2\": \"suite 312\",\n \"city\": \"SomeWheresVille\",\n \"state\": \"Florida\",\n \"zip\": \"22211-123\",\n \"patientId\": \"MRN0001234\",\n }","options":{"raw":{"language":"json"}}}},"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\n \"error\": \"Missing required data fields in source JSON: dateOfBirth\"\n}"}],"_postman_id":"2bf8a7ce-9893-433c-adcc-4f72d1d362fd"}],"id":"f42a7fa9-bd5a-4c9a-8009-f84ba7f93e2e","description":"EasyResponder Repostory is a turnkey interoperability clinical repository that enables healthcare organizations to participate in national health information networks—such as Carequality and CommonWell—even if they do not have the technical infrastructure to process complex patient information requests internally.
\nNational Network Connectivity:
EasyResponder responds to queries for patient records from national networks (e.g., Carequality, CommonWell) on behalf of your organization.
Patient Index and Clinical Repository:
The service acts as both a Master Patient Index (MPI) and a clinical document repository for your organization.
Simple Onboarding:
Customers upload their patient data and documents to EasyResponder via a simple to use REST API. We manage and fulfill queries from the national networks using your data.
Organizations without robust health IT infrastructure can use EasyResponder to seamlessly participate in nationwide clinical data exchange. By managing network queries and responding on your behalf,
\n","_postman_id":"f42a7fa9-bd5a-4c9a-8009-f84ba7f93e2e"}],"variable":[{"key":"version","value":"","type":"default"}]}