IHE, or "Integrating the Healthcare Enterprise," is a standards profiling organization that maintains best practices for exchanging healthcare data within and between various healthcare communities. These communities are often location-based and share patient consent agreements via nationwide health information exchange (HIE) networks such as Carequality and CommonWell. Querying these networks requires supplying patient demographics to search and retrieve information from various communities linked in the system.

To utilize networks that support the IHE protocol, your solution must provide a bidirectional path for fetching and sharing medical documents. In IHE, the term "Initiating Gateway" refers to finding and retrieving patient records from network communities. Your solution must also support the reverse data flow by providing records in your system back to other communities in the network when others are searching for patients with matching demographics. This is called a "Responding Gateway" in IHE. You can read more about these gateways in the IHE white paper.

OneRecord simplifies this process using HealthConnect to supply the communications required to support Initiating and Responding Gateways. To use the Initiating gateway, solutions only need to make OneRecord API calls to query for patient documents, and OneRecord and Health Share handle the complexities of securing these calls. To use the Responding Gateway, some part of your solution's back end must serve the required endpoints that respond with patient records when requested. These endpoints should be secured between your solution and OneRecord to ensure IHE compliance and enable your system to return records to the network when needed. For more information on setting this up, see "Setting up a Responding Gateway."

Overview of the 3 National Networks

OneRecord API is connected to all 3 national networks, Carequality, eHealth Exchange and CommonWell Health Alliance. While the overall process is the same (patient query, document query, document retrieve) they each have some variation.

Carequality is a completely federated network. The only technical infrastructure they support is a participant directory. To find your patient, you must query the Carequality Directory for organizations in proximity to your patient and then send a Patient Query Transaction to each. For organizations where your patient is found the next step is to query for available documents and then retrieve those documents.

eHealth Exchange is also a federated network but has a Hub to facilitate, and track, the transactions that flow within the network. eHealth Exchange does have a directory, like Carequality, and you can query each location, but you also can leverage the Hub and have it query multiple sites for you. You can either have it query the full State or query the Hospital Referral Region (HRR). HRR is a geographic region that represents a portion of one or more areas where patients are typically referred to, even crossing state lines. An example would be someone living in Chattanooga, TN but the HRR extends into Alabama, and Georgia.

CommonWell Health Alliance is a partially centralized network that supports a Master Patient Index (MPI) and a Record Locator Service (RLS). The initial step in interacting with CommonWell is to Register your patient at the organization they are associated with. This populates the Master Patient Index and creates a Person record and links instances of that Person as a Patient with each organization that has Registered them. This allows the Record Locator to respond to queries with all the organizations a Patient has been to.

Overview of the ORAPI Network Query APIs

Initiating Gateway Network Services:

For Carequality and eHealth Exchange

(optional) Patient Query - find out if the location has a patient match
(optional) Document Query - when a patient is matched, query the location for any available clinical documents. The response contains document IDs.
Combined Patient / Document Query - this combines both the patient and document queries. If the patient is found the returning payload will return document IDs.
Document Retrieve - for each of the Document IDs you retrieve them with this transaction.

For CommonWell

New CommonWell 2.0 transaction details to come

Setting Up an Initiating Gateway

ORAPI setup requirements

Before proceeding with querying patient records using the Initiating Gateway, ensure that your OneRecord API account's Access Tokens are correctly configured and your responding gateway setup has been connected to OneRecord and verified as secure. Once your account is set up and connected to the networks, you can move forward with the following high-level steps:

For Carequality and eHealth Exchange

(optional) Patient Query - find out if the location has a patient match
(optional) Document Query - when a patient is matched, query the location for any available clinical documents. The response contains document IDs.
Combined Patient / Document Query - this combines both the patient and document queries. If the patient is found the returning payload will return document IDs.
Document Retrieve - for each of the Document IDs you retrieve them with this transaction.

For CommonWell

New CommonWell 2.0 transaction details to come

Patient Query

This endpoint is particularly useful when you want to find a patient before querying for their documents.

Try It Here, or use the following Integrator Service URL:

POST https://integrator.stage.onerecord.com/integrator/v2/patient/query

{
    "patient": {
        "firstName": "Amy",
        "lastName": "Davidson",
        "dob": "1983-10-17",
        "gender": "F",
        "telephone": "4179890987",
        "street": "809 First Ave",
        "city": "Springfield",
        "state": "MO",
        "zip": "65801",
        "country": "USA"
    },
    "filter": {
        "networkName": "Carequality|eHealth Exchange",
        "organizationId": "2.16.840.1.113883.3.7080.2.4.1003.101"
    }
}

The following is an example of a patient query response when a patient is found.

{
    "clientRequestId": "356fc4bd-cc42-4cbd-ae2f-0c0a9811965f",
    "responses": [
        {
            "networkRequestId": "a754451c-3c6f-458d-b5cd-1fffb6822f74",
            "networkName": "Carequality",
            "patients": [
                {
                    "dob": "1983-10-17",
                    "firstName": "Amy",
                    "gender": "F",
                    "telephone": "+1-417-989-0987",
                    "lastName": "Davidson",
                    "city": "Springfield",
                    "state": "MO",
                    "street": "809 First Ave",
                    "zip": "65801",
                    "identifiers": [
                        {
                            "value": "OR-MRN-1913",
                            "authority": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
                            "community": "2.16.840.1.113883.3.7080.2.4.1003.101"
                        }
                    ]
                }
            ],
            "acknowledgementTypeCode": "AA",
            "queryResponseCode": "OK"
        }
    ]
}

The following is an example of a patient query response when no patient is found.

{
    "clientRequestId": "9a9588e0-0908-4540-8a79-1829dad35b34",
    "responses": [
        {
            "networkRequestId": "cb741dc6-fad1-4186-98d2-a6f77461cb9e",
            "networkName": "Carequality",
            "patients": [],
            "acknowledgementTypeCode": "AA",
            "queryResponseCode": "NF"
        }
    ]
}

Carequality - To perform a Patient Query in Carequality, you must first identify which organizations to query. This is done by obtaining the organizations OID (Object Identifier), which required by the API.

You can retrieve the relevant Organization OIDs by using the ORAPI Carequality Directory. The following endpoint allows you to search for organizations within a specified radius (in miles) of a patient's address:

https://directory.stage.onerecord.com/directory/v1/client/carequality/endpoint/geo/search/address/radius

Once you have obtained the list of OIDs, you can initiate a Patient Query by sending the patient's demographic information, along with the organization OID, to each organization via the API.

Targeted Carequality Patient Query

Set the following elements in the "filter" object of the request body:

networkName = Carequality
organizationId = urn:oid:<targeted_organization_oid> (e.g., "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101")

{
    "patient": {
        "firstName": "Amy",
        "lastName": "Davidson",
        "dob": "1983-10-17",
        "gender": "F",
        "telephone": "4179890987",
        "street": "809 First Ave",
        "city": "Springfield",
        "state": "MO",
        "zip": "65801",
        "country": "USA"
    },
    "filter": {
        "networkName": "Carequality",
        "organizationId": "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101"
    }
}

eHealth Exchange - Similar to Carequality, you can query a specific organization in eHealth Exchange by using its OID, if you know it. Please note that the eHealth Exchange Directory is not yet available as of February 2, 2026.

eHealth Exchange Hub Patient Query

The eHealth Exchange allows a few different querying options. The Hub allows you to:

Query a specific organization by OID, or
Query all organizations within an entire state, or
Query organizations by Hospital Referral Region (HRR)

Set the following elements in the "filter" object of the request body to perform a targeted patient query:

networkName = eHealth Exchange
organizationId = urn:oid:<targeted_organization_oid> (e.g., "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101")

{
    "patient": {
        "firstName": "Amy",
        "lastName": "Davidson",
        "dob": "1983-10-17",
        "gender": "F",
        "telephone": "4179890987",
        "street": "809 First Ave",
        "city": "Springfield",
        "state": "MO",
        "zip": "65801",
        "country": "USA"
    },
    "filter": {
        "networkName": "eHealth Exchange",
        "organizationId": "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101"
    }
}

Set the following elements in the "filter" object of the request body to perform a state-based patient query:

networkName = eHealth Exchange
organizationId = GeoStateXX (where XX= the state's 2-character abbreviation; e.g., "GeoStateMO" for Missouri)

{
    "patient": {
        "firstName": "Amy",
        "lastName": "Davidson",
        "dob": "1983-10-17",
        "gender": "F",
        "telephone": "4179890987",
        "street": "809 First Ave",
        "city": "Springfield",
        "state": "MO",
        "zip": "65801",
        "country": "USA"
    },
    "filter": {
        "networkName": "eHealth Exchange",
        "organizationId": "GeoStateMO"
    }
}

Set the following elements in the "filter" object of the request body to perform an HRR-based patient query:

networkName = eHealth Exchange
organizationId = HRRFANOUT

These options enable broader or more targeted searches across the eHealth Exchange network.

{
    "patient": {
        "firstName": "Amy",
        "lastName": "Davidson",
        "dob": "1983-10-17",
        "gender": "F",
        "telephone": "4179890987",
        "street": "809 First Ave",
        "city": "Springfield",
        "state": "MO",
        "zip": "65801",
        "country": "USA"
    },
    "filter": {
        "networkName": "eHealth Exchange",
        "organizationId": "HRRFANOUT"
    }
}

Registering Patients for CommonWell

Before querying records for patients with data managed by CommonWell, it's essential to register the patient and their demographics. OneRecord API offers a Register Patient endpoint through the Integrator Service to facilitate this process.

There's no harm in attempting to register a patient who has previously been registered, as the response will simply indicate that the patient is already in the system. However, it's beneficial for your solution to remember which patients have been registered to optimize the number of API calls made and improve the overall performance of your product and the network.

Try It Here, or use the following Integrator Service URL:

The new patient register endpoint is currently under development and will be available soon.

Document Query

This endpoint is particularly useful when you have already queried for a patient and have their identifier(s), and you want to query for documents without having to provide the full patient demographics again.

Try It Here, or use the following Integrator Service URL:

POST https://integrator.stage.onerecord.com/integrator/v2/document/query

{
    "patient": {
        "identifiers": [
            {
                "value": "OR-MRN-1913",
                "authority": "2.16.840.1.113883.3.7080.2.4.1003.101.1"
            }
        ]
    },
    "filter": {
        "networkName": "Carequality|eHealth Exchange",
        "organizationId": "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101",
        "includeOnDemandDocuments": true,
        "includeStableDocuments": true,
        "serviceStartTimeFrom": "2000-01-01",
        "serviceStartTimeTo": "",
        "serviceStopTimeFrom": "",
        "serviceStopTimeTo": "",
        "includeApprovedDocuments": true,
        "includeDeprecatedDocuments": false
    }
}

The following is an example of a document query response when documents are found.

{
    "clientRequestId": "5323bc29-6975-49a5-bc40-7a8a99745505",
    "responses": [
        {
            "networkRequestId": "346abdbc-a160-41bd-86c1-343349f75d1c",
            "networkName": "Carequality",
            "documentCount": "2",
            "documents": [
                {
                    "documentUniqueId": "23b26ef6-6a2e-4a9e-9c6c-2b02629c88b7",
                    "repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
                    "homeCommunityId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
                    "mimeType": "text/xml",
                    "classCode": {
                        "code": "34133-9",
                        "codingScheme": "2.16.840.1.113883.6.1",
                        "name": "Ophthalmology Studies"
                    },
                    "creationTime": "2026-02-03",
                    "name": "Query for Documents Test Document D-27",
                    "comments": "This is the comment",
                    "serviceStartTime": "2007-03-15",
                    "serviceStopTime": "2007-04-01",
                    "languageCode": "en-US",
                    "authorInstitution": "ONC Validation",
                    "authorPerson": "Aaron Jones",
                    "formatCode": {
                        "code": "urn:ihe:pcc:edr:2007",
                        "codingScheme": "2.16.840.1.113883.3.88.12.80.73",
                        "name": "Emergency Department Referral (EDR)"
                    },
                    "healthCareFacilityTypeCode": {
                        "code": "36125001",
                        "codingScheme": "2.16.840.1.113883.6.96",
                        "name": "Hospital-trauma center"
                    },
                    "status": "Approved",
                    "availability": "Offline",
                    "type": "OnDemand",
                    "practiceSettingCode": {
                        "code": "408478003",
                        "codingScheme": "2.16.840.1.113883.6.96",
                        "name": "Critical care medicine"
                    },
                    "typeCode": {
                        "code": "28619-5",
                        "codingScheme": "2.16.840.1.113883.6.1",
                        "name": "Ophthalmology Studies"
                    },
                    "confidentialityCode": {
                        "code": "N",
                        "codingScheme": "2.16.840.1.113883.5.25",
                        "name": "Normal"
                    },
                    "patientIdentifier": "OR-MRN-1913^^^&2.16.840.1.113883.3.7080.2.4.1003.101.1&ISO"
                },
                {
                    "documentUniqueId": "456a1292-a777-f69c-789d-b54n7op5e980",
                    "repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
                    "homeCommunityId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
                    "hash": "3f786850e387550fdab836ed7e6dc881de23001b",
                    "size": "1024",
                    "mimeType": "text/xml",
                    "classCode": {
                        "code": "34133-9",
                        "codingScheme": "2.16.840.1.113883.6.1",
                        "name": "Ophthalmology Studies"
                    },
                    "creationTime": "2009-05-13",
                    "name": "Query for Documents Test Document D-1",
                    "comments": "This is the comment",
                    "serviceStartTime": "2007-03-15",
                    "serviceStopTime": "2007-04-01",
                    "languageCode": "en-us",
                    "authorInstitution": "ONC Validation",
                    "authorPerson": "Adam Hunter",
                    "formatCode": {
                        "code": "urn:ihe:pcc:edr:2007",
                        "codingScheme": "2.16.840.1.113883.3.88.12.80.73",
                        "name": "Emergency Department Referral (EDR)"
                    },
                    "healthCareFacilityTypeCode": {
                        "code": "36125001",
                        "codingScheme": "2.16.840.1.113883.6.96",
                        "name": "Hospital-trauma center"
                    },
                    "status": "Approved",
                    "availability": "Offline",
                    "type": "Stable",
                    "practiceSettingCode": {
                        "code": "408478003",
                        "codingScheme": "2.16.840.1.113883.6.96",
                        "name": "Critical care medicine"
                    },
                    "typeCode": {
                        "code": "28619-5",
                        "codingScheme": "2.16.840.1.113883.6.1",
                        "name": "Ophthalmology Studies"
                    },
                    "confidentialityCode": {
                        "code": "N",
                        "codingScheme": "2.16.840.1.113883.5.25",
                        "name": "Normal"
                    },
                    "patientIdentifier": "OR-MRN-1913^^^&2.16.840.1.113883.3.7080.2.4.1003.101.1&ISO"
                }
            ]
        }
    ]
}

The following is an example of a document query response when no documents are found.

{
    "clientRequestId": "7ecba908-80a8-48f4-a349-a73453f0436d",
    "responses": [
        {
            "networkRequestId": "606b7291-3a09-453e-81c4-2bef0b2b8cde",
            "networkName": "Carequality",
            "documentCount": "0",
            "documents": []
        }
    ]
}

Carequality - To perform a Document Query in Carequality, you must first obtain the identifiers of the patient to query. This is done by performing a Patient Query first.

Carequality Document Query

Set the following elements in the patient "identifiers" array of the request body:

value = <patient_identifier_value> (e.g., "OneRecord-Test-Patient-101")
authority = <patient_identifier_authority_oid> (e.g., "2.16.840.1.113883.3.7080.2.4.1003.101.1")

Set the following elements in the "filter" object of the request body:

networkName = Carequality
organizationId = urn:oid:<organization_oid> (e.g., "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101")

{
    "patient": {
        "identifiers": [
            {
                "value": "OR-MRN-1913",
                "authority": "2.16.840.1.113883.3.7080.2.4.1003.101.1"
            }
        ]
    },
    "filter": {
        "networkName": "Carequality",
        "organizationId": "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101",
        "includeOnDemandDocuments": true,
        "includeStableDocuments": true,
        "serviceStartTimeFrom": "2000-01-01",
        "serviceStartTimeTo": "",
        "serviceStopTimeFrom": "",
        "serviceStopTimeTo": "",
        "includeApprovedDocuments": true,
        "includeDeprecatedDocuments": false
    }
}

eHealth Exchange - To perform a Document Query in eHealth Exchange, you must first obtain the identifiers of the patient to query. This is done by performing a Patient Query first.

eHealth Exchange Document Query

Set the following elements in the patient "identifiers" array of the request body:

value = <patient_identifier_value> (e.g., "OneRecord-Test-Patient-101")
authority = <patient_identifier_authority_oid> (e.g., "2.16.840.1.113883.3.7080.2.4.1003.101.1")

Set the following elements in the "filter" object of the request body:

networkName = eHealth Exchange
organizationId = urn:oid:<organization_oid> (e.g., "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101")

{
    "patient": {
        "identifiers": [
            {
                "value": "OR-MRN-1913",
                "authority": "2.16.840.1.113883.3.7080.2.4.1003.101.1"
            }
        ]
    },
    "filter": {
        "networkName": "eHealth Exchange",
        "organizationId": "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101",
        "includeOnDemandDocuments": true,
        "includeStableDocuments": true,
        "serviceStartTimeFrom": "2000-01-01",
        "serviceStartTimeTo": "",
        "serviceStopTimeFrom": "",
        "serviceStopTimeTo": "",
        "includeApprovedDocuments": true,
        "includeDeprecatedDocuments": false
    }
}

Combined Query

The Combined Query endpoint is used to perform both the Patient Query and Document Query in a single API call. This is particularly useful when you want to simplify the process of querying for patient documents without having to make multiple requests.

Try It Here, or use the following Integrator Service URL:

POST https://integrator.stage.onerecord.com/integrator/v2/combined/query

{
    "patient": {
        "firstName": "Amy",
        "lastName": "Davidson",
        "dob": "1983-10-17",
        "gender": "F",
        "telephone": "4179890987",
        "street": "809 First Ave",
        "city": "Springfield",
        "state": "MO",
        "zip": "65801",
        "country": "USA"
    },
    "filter": {
        "networkName": "Carequality|eHealth Exchange",
        "organizationId": "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101"
    }
}

The following is an example of a response when a patient is found and documents are available.

{
    "clientRequestId": "0a31cc55-30a6-4c96-8065-952a740cf448",
    "responses": [
        {
            "patientQueryNetworkRequestId": "2f039a44-9eaa-439a-9703-7833c3d28bcb",
            "documentQueryNetworkRequestId": "89d49e98-4a71-40d0-97e5-e986c86090e7",
            "networkName": "Carequality",
            "patient": {
                "dob": "1983-10-17",
                "firstName": "Amy",
                "gender": "F",
                "telephone": "+1-417-989-0987",
                "lastName": "Davidson",
                "city": "Springfield",
                "state": "MO",
                "street": "809 First Ave",
                "zip": "65801",
                "identifiers": [
                    {
                        "value": "OR-MRN-1913",
                        "authority": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
                        "community": "2.16.840.1.113883.3.7080.2.4.1003.101"
                    }
                ]
            },
            "documentCount": "2",
            "documents": [
                {
                    "documentUniqueId": "23b26ef6-6a2e-4a9e-9c6c-2b02629c88b7",
                    "repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
                    "homeCommunityId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
                    "mimeType": "text/xml",
                    "classCode": {
                        "code": "34133-9",
                        "codingScheme": "2.16.840.1.113883.6.1",
                        "name": "Ophthalmology Studies"
                    },
                    "creationTime": "2026-02-04",
                    "name": "Query for Documents Test Document D-27",
                    "comments": "This is the comment",
                    "serviceStartTime": "2007-03-15",
                    "serviceStopTime": "2007-04-01",
                    "languageCode": "en-US",
                    "authorInstitution": "ONC Validation",
                    "authorPerson": "Aaron Jones",
                    "formatCode": {
                        "code": "urn:ihe:pcc:edr:2007",
                        "codingScheme": "2.16.840.1.113883.3.88.12.80.73",
                        "name": "Emergency Department Referral (EDR)"
                    },
                    "healthCareFacilityTypeCode": {
                        "code": "36125001",
                        "codingScheme": "2.16.840.1.113883.6.96",
                        "name": "Hospital-trauma center"
                    },
                    "status": "Approved",
                    "availability": "Offline",
                    "type": "OnDemand",
                    "practiceSettingCode": {
                        "code": "408478003",
                        "codingScheme": "2.16.840.1.113883.6.96",
                        "name": "Critical care medicine"
                    },
                    "typeCode": {
                        "code": "28619-5",
                        "codingScheme": "2.16.840.1.113883.6.1",
                        "name": "Ophthalmology Studies"
                    },
                    "confidentialityCode": {
                        "code": "N",
                        "codingScheme": "2.16.840.1.113883.5.25",
                        "name": "Normal"
                    },
                    "patientIdentifier": "OR-MRN-1913^^^&2.16.840.1.113883.3.7080.2.4.1003.101.1&ISO"
                },
                {
                    "documentUniqueId": "456a1292-a777-f69c-789d-b54n7op5e980",
                    "repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
                    "homeCommunityId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
                    "hash": "3f786850e387550fdab836ed7e6dc881de23001b",
                    "size": "1024",
                    "mimeType": "text/xml",
                    "classCode": {
                        "code": "34133-9",
                        "codingScheme": "2.16.840.1.113883.6.1",
                        "name": "Ophthalmology Studies"
                    },
                    "creationTime": "2009-05-13",
                    "name": "Query for Documents Test Document D-1",
                    "comments": "This is the comment",
                    "serviceStartTime": "2007-03-15",
                    "serviceStopTime": "2007-04-01",
                    "languageCode": "en-us",
                    "authorInstitution": "ONC Validation",
                    "authorPerson": "Adam Hunter",
                    "formatCode": {
                        "code": "urn:ihe:pcc:edr:2007",
                        "codingScheme": "2.16.840.1.113883.3.88.12.80.73",
                        "name": "Emergency Department Referral (EDR)"
                    },
                    "healthCareFacilityTypeCode": {
                        "code": "36125001",
                        "codingScheme": "2.16.840.1.113883.6.96",
                        "name": "Hospital-trauma center"
                    },
                    "status": "Approved",
                    "availability": "Offline",
                    "type": "Stable",
                    "practiceSettingCode": {
                        "code": "408478003",
                        "codingScheme": "2.16.840.1.113883.6.96",
                        "name": "Critical care medicine"
                    },
                    "typeCode": {
                        "code": "28619-5",
                        "codingScheme": "2.16.840.1.113883.6.1",
                        "name": "Ophthalmology Studies"
                    },
                    "confidentialityCode": {
                        "code": "N",
                        "codingScheme": "2.16.840.1.113883.5.25",
                        "name": "Normal"
                    },
                    "patientIdentifier": "OR-MRN-1913^^^&2.16.840.1.113883.3.7080.2.4.1003.101.1&ISO"
                }
            ]
        }
    ]
}

The following is an example of a response when no patient is found.

{
    "clientRequestId": "162d8eb1-cfb7-4565-a9e4-725e85c66a99",
    "responses": [
        {
            "patientQueryNetworkRequestId": "0012f29b-a4be-48c5-a0ac-5c00c56030af",
            "networkName": "Carequality",
            "patient": null,
            "documents": []
        }
    ]
}

The following is an example of a response when a patient is found but no documents are available.

{
    "clientRequestId": "0a31cc55-30a6-4c96-8065-952a740cf448",
    "responses": [
        {
            "patientQueryNetworkRequestId": "2f039a44-9eaa-439a-9703-7833c3d28bcb",
            "documentQueryNetworkRequestId": "89d49e98-4a71-40d0-97e5-e986c86090e7",
            "networkName": "Carequality",
            "patient": {
                "dob": "1983-10-17",
                "firstName": "Amy",
                "gender": "F",
                "telephone": "+1-417-989-0987",
                "lastName": "Davidson",
                "city": "Springfield",
                "state": "MO",
                "street": "809 First Ave",
                "zip": "65801",
                "identifiers": [
                    {
                        "value": "OR-MRN-1913",
                        "authority": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
                        "community": "2.16.840.1.113883.3.7080.2.4.1003.101"
                    }
                ]
            },
            "documentCount": "0",
            "documents": []
        }
    ]
}

Carequality - To perform a Combined Patient / Document Query in Carequality, you must provide patient demographics along with the organization OID to query.

Carequality Combined Patient / Document Query

Set the following elements in the "filter" object of the request body:

networkName = Carequality
organizationId = urn:oid:<organization_oid> (e.g., "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101")

{
    "patient": {
        "firstName": "Amy",
        "lastName": "Davidson",
        "dob": "1983-10-17",
        "gender": "F",
        "telephone": "4179890987",
        "street": "809 First Ave",
        "city": "Springfield",
        "state": "MO",
        "zip": "65801",
        "country": "USA"
    },
    "filter": {
        "networkName": "Carequality",
        "organizationId": "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101"
    }
}

eHealth Exchange - To perform a Combined Patient / Document Query in eHealth Exchange, you must provide patient demographics along with the organization OID to query.

eHealth Exchange Combined Patient / Document Query

Set the following elements in the "filter" object of the request body:

networkName = eHealth Exchange
organizationId = urn:oid:<organization_oid> (e.g., "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101")

{
    "patient": {
        "firstName": "Amy",
        "lastName": "Davidson",
        "dob": "1983-10-17",
        "gender": "F",
        "telephone": "4179890987",
        "street": "809 First Ave",
        "city": "Springfield",
        "state": "MO",
        "zip": "65801",
        "country": "USA"
    },
    "filter": {
        "networkName": "eHealth Exchange",
        "organizationId": "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101"
    }
}

Document Retrieve

The Document Retrieve endpoint is used to retrieve specific documents once you have their unique identifiers. This is typically done after performing a Document Query to obtain the necessary document IDs. This endpoint allows retrieval of multiple documents in a single request. For vendors, like Epic, that can send back 100s of files, it is recommended to break that list up into smaller transactions, e.g. 5 at a time, to prevent timeouts.

After retrieving the documents, you'll receive a base64-encoded string in the response body. When decoded, this string represents the data of the document. Documents can be in various formats. The most popular formats are CDA XML documents or PDF documents, but sometimes the decoded result can be an image or something else.

You can download full examples of the various document types from the Data Sources Page.

Try It Here, or use the following Integrator Service URL:

POST https://integrator.stage.onerecord.com/integrator/v2/document/retrieve

{
    "documents": [
        {
            "documentUniqueId": "456a1292-a777-f69c-789d-b54n7op5e980",
            "repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
            "homeCommunityId": "2.16.840.1.113883.3.7080.2.4.1003.101.1"
        }
    ],
    "filter": {
        "networkName": "Carequality|eHealth Exchange",
        "organizationId": "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101"
    }
}

The following is an example of a successful document retrieve response.

{
    "clientRequestId": "71e6c157-27cf-4e65-b526-32ce2bdb6f80",
    "responses": [
        {
            "networkRequestId": "609a5c61-a6d1-4abf-80f5-656f7cd97ee0",
            "networkName": "Carequality",
            "document": {
                "documentUniqueId": "456a1292-a777-f69c-789d-b54n7op5e980",
                "repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
                "homeCommunityId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
                "document": "PD94bWwgdmVyc2lvbj0iMS...Y2FsRG9jdW1lbnQ+"
            }
        }
    ]
}

The following is an example of a document retrieve response when there is an error retrieving the document.

{
    "clientRequestId": "d2b912bd-3aaa-4a02-976f-05cb92d50335",
    "responses": [
        {
            "networkRequestId": "39c6cfa0-2c66-4ca6-b439-02184eff6e85",
            "networkName": "Carequality",
            "document": {
                "documentUniqueId": "456a1292-a777-f69c-789d-b54n7op5e980a",
                "repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
                "homeCommunityId": "2.16.840.1.113883.3.7080.2.4.1003.101.1"
            },
            "error": {
                "code": "5001",
                "description": "ERROR #5001: There was an error retrieving document(s)"
            }
        }
    ]
}

Carequality - To perform a Document Retrieve in Carequality, you must first obtain the identifiers of the document to retrieve. This is done by performing a Document Query first.

Carequality Document Retrieve

Set the following elements in the document fields of the request body:

documentUniqueId = <document_unique_id> (e.g., "456a1292-a777-f69c-789d-b54n7op5e980")
repositoryUniqueId = <repository_unique_id> (e.g., "2.16.840.1.113883.3.7080.2.4.1003.101.1")
homeCommunityId = <home_community_id> (e.g., "2.16.840.1.113883.3.7080.2.4.1003.101.1")

Set the following elements in the "filter" object of the request body:

networkName = Carequality
organizationId = urn:oid:<organization_oid> (e.g., "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101")

{
    "documents": [
        {
            "documentUniqueId": "456a1292-a777-f69c-789d-b54n7op5e980",
            "repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
            "homeCommunityId": "2.16.840.1.113883.3.7080.2.4.1003.101.1"
        }
    ],
    "filter": {
        "networkName": "Carequality",
        "organizationId": "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101"
    }
}

eHealth Exchange - To perform a Document Retrieve in eHealth Exchange, you must first obtain the identifiers of the document to retrieve. This is done by performing a Document Query first.

eHealth Exchange Document Retrieve

Set the following elements in the document fields of the request body:

documentUniqueId = <document_unique_id> (e.g., "456a1292-a777-f69c-789d-b54n7op5e980")
repositoryUniqueId = <repository_unique_id> (e.g., "2.16.840.1.113883.3.7080.2.4.1003.101.1")
homeCommunityId = <home_community_id> (e.g., "2.16.840.1.113883.3.7080.2.4.1003.101.1")

Set the following elements in the "filter" object of the request body:

networkName = eHealth Exchange
organizationId = urn:oid:<organization_oid> (e.g., "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101")

{
    "documents": [
        {
            "documentUniqueId": "456a1292-a777-f69c-789d-b54n7op5e980",
            "repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
            "homeCommunityId": "2.16.840.1.113883.3.7080.2.4.1003.101.1"
        }
    ],
    "filter": {
        "networkName": "eHealth Exchange",
        "organizationId": "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101"
    }
}

Setting Up a Responding Gateway

In most cases, solutions connecting to networks via IHE must support a Responding Gateway. Your solution must be able to participate in network searches, providing records when others in the network find and request them.

One exception in which a Responding Gateway is not required would be for solutions that conform to the Delegation of Authority use case. This is where no new patient records are being created by the Delegate, and records are only ever queried. This will be determined as part of your solution's Certification Process.

How The Responding Gateway Works

To set up a Responding Gateway, your solution must enable patients and documents to be queryable and retrievable. There are three main requirements that must be supported:

Patient Lookup Query (via Demographics): Identifies whether a patient with matching demographics exists within your data repository, for a specified organization.
Document Gateway Query: Once Patient is identified this transaction identifies if your solution houses data for the patient.
Document Retrieval: This transaction retrieves the actual data of a document found in the previous step within your data repository.

It is recommended to separate your Patient Query and Document Query endpoints due to the potential for high amounts of Patient Query transactions that may be received.

You, as the solution provider must set up the appropriate means to retrieve and reliably serve these endpoints so that OneRecord API can maintain constant contact with your systems, upholding the commitment to enabling IHE transactions. OneRecord API authenticates to your solution's system and calls these endpoints as network searches are performed.

Testing Your Responding Gateway Configuration and Communication with OneRecord API

Setting up your Responding Gateway is an essential step in the onboarding process if you wish to connect with healthcare interoperability networks. As part of this process, your developers will provide OneRecord with a secure means of authenticating with their endpoints, which are listening for requests from the network.

To test your Responding Gateway's functionality and communication with OneRecord API, first complete and internally test your team's implementation of the required endpoints. Then, for each OneRecord API environment (Stage, Pre-Production, and Production), provide OneRecord with the corresponding URLs that fulfill the Responding Gateway requirements, and a mTLS certificate for Production environment, along with the steps for securely authenticating with your endpoints.

Performing these tests will help you refine your patient search algorithms and optimize internal logistics for document queries and retrievals, ensuring that your Responding Gateway is correctly set up and able to communicate effectively with OneRecord API.

Supporting the Patient Lookup Query

To support the Patient Lookup Query for the Responding Gateway, your solution must be able to handle requests whenever users search for establishments connected to the Carequality IHE network that have potentially interacted with a specific patient. CommonWell, on the other hand, uses a different patient registration mechanism. Clients query CommonWell for a linked patient match and need not rely on this endpoint for patient lookups.

Your endpoint should accept patient demographics as input and return relevant search results containing the patient's local identifier in your system. Carequality and eHealth Exchange use this local patient identifier to make any subsequent document queries requested in your system for the given patient.

Your development team integrating with OneRecord API is responsible for architecting the algorithm that returns meaningful results from your system and maintaining reliable uptime. The following example outlines possible fields that could be sent in the request body and the minimum requirements the patient query response should return.

GET https://<your-app-url>/<path-for your-patient-query-endpoint>

{
    "initiatorRequestId": "[optional-String]",
    "patient": {
        "firstName": "String",
        "lastName": "String",
        "gender": "[M|F|U]",
        "dob": "YYYY-MM-DD",
        "telephone": "String",
        "street": "String",
        "city": "String",
        "state": "String(2)(State Abbreviation)",
        "zip": "String",
        "country": "String"
    },
    "network": {
        "name": "[Carequality|eHealth Exchange]",
        "purposeOfUse": "String",
        "initiatingOrganization": {
            "name": "String",
            "identifier": "String(OID format)"
        },
        "respondingOrganization": {
            "name": "String",
            "identifier": "String(OID format)"
        },
        "initiatingUser": {
            "name": "String",
            "email": "String"
        }
    }
}

For example, here is a sample request body for a patient lookup query:

{
    "patient": {
        "firstName": "Robert",
        "lastName": "Carson",
        "gender": "M",
        "dob": "1960-02-10"
    },
    "network": {
        "respondingOrganization": {
            "name": "OneRecord",
            "identifier": "2.16.840.1.113883.3.7080.2.4.1003.101"
        }
    }
}

The response should a list of patient matches:

{
    "initiatorRequestId": "[optional-String]",
    "responses": [
        {
            "messageId": "[optional-String]",
            "patients": [
                {
                    "firstName": "String",
                    "lastName": "String",
                    "dob": "YYYY-MM-DD",
                    "gender": "[M|F|U]",
                    "telephone": "String",
                    "street": "String",
                    "city": "String",
                    "state": "String(2)(State Abbreviation)",
                    "zip": "String",
                    "identifiers": [
                        {
                            "value": "String",
                            "authority": "String(OID format)"
                        }
                    ]
                }
            ]
        }
    ]
}

For example, the following is a sample response when a patient is found:

{
    "messageId": "123456789",
    "patients": [
        {
            "firstName": "Robert",
            "lastName": "Carson",
            "dob": "1960-02-10",
            "gender": "M",
            "telephone": "+1-303-454-0909",
            "street": "290 Jackson Lane",
            "city": "Boulder",
            "state": "CO",
            "zip": "80301",
            "identifiers": [
                {
                    "value": "OneRecord-Test-Patient-101",
                    "authority": "2.16.840.1.113883.3.7080.2.4.1003.101.1"
                }
            ]
        }
    ]
}

The following is a sample response when a patient is not found:

{
    "patients": []
}

You can also exclude the patient array and return an error message like this:

{
    "status": "FAILED",
    "error": "No matching patient found"
}

In this example, the "status" and "error" fields are optional and are actually ignored by OneRecord API, but they may be useful for your internal logging and debugging purposes. The exclusion of the "patients" array or an empty "patients" array is sufficient to indicate that no matching patient was found.

Supporting the Document Gateway Query

To support the Document Query for the Responding Gateway, your solution must be able to handle requests whenever users search for establishments connected to the Carequality IHE network that have potentially interacted with a specific patient.

Your endpoint should accept the patient identifier as input and return relevant search results containing documents for the given patient.

Your development team integrating with OneRecord API is responsible for architecting the algorithm that returns meaningful results from your system and maintaining reliable uptime. The following example outlines the minimum requirements for the document properties your endpoint must be able to search on.

GET https://<your-app-url>/<path-for your-document-query-endpoint>

{
    "initiatorRequestId": "[optional-String]",
    "patient": {
        "identifiers": [
            {
                "value": "String",
                "authority": "String(OID format)"
            }
        ]
    },
    "network": {
        "name": "[Carequality|eHealth Exchange]",
        "purposeOfUse": "String",
        "initiatingOrganization": {
            "name": "String",
            "identifier": "String(OID format)"
        },
        "respondingOrganization": {
            "name": "String",
            "identifier": "String(OID format)"
        },
        "initiatingUser": {
            "name": "String",
            "email": "String"
        }
    }
}

For example, here is a sample request body for a document query:

{
    "patient": {
        "identifiers": [
            {
                "value": "OneRecord-Test-Patient-101",
                "authority": "2.16.840.1.113883.3.7080.2.4.1003.101.1"
            }
        ]
    },
    "network": {
        "respondingOrganization": {
            "name": "OneRecord",
            "identifier": "2.16.840.1.113883.3.7080.2.4.1003.101"
        }
    }
}

Your endpoint should support returning multiple documents with the following format:

{
    "messageId": "[optional-String]",
    "documents": [
        {
            "documentUniqueId": "String",
            "repositoryUniqueId": "String",
            "homeCommunityId": "String",
            "patientIdentifier": "String",
            "title": "String",
            "comments": "String",
            "creationTime": "YYYYMMDD",
            "serviceStartTime": "YYYYMMDD",
            "serviceStopTime": "YYYYMMDD",
            "hash": "String",
            "size": "int",
            "mimeType": "String",
            "languageCode": "String",
            "status": "[Approved|Deprecated|Submitted]",
            "availability": "[Online|Offline]",
            "type": "[OnDemand|Stable]",
            "authorInstitution": "(String - Name)^^^^^^^^^(String - OID)",
            "authorPerson": "^(String - Last Name)^(String - First Name)^^^",
            "legalAuthenticator": "^(String - Last Name)^(String - First Name)^^^(String - Prefix)^(String - Name Type Code)",
            "classCode": {
                "code": "String",
                "codingScheme": "(String - OID)",
                "name": "String"
            },
            "formatCode": {
                "code": "String",
                "codingScheme": "(String - OID)",
                "name": "String"
            },
            "healthCareFacilityTypeCode": {
                "code": "String",
                "codingScheme": "(String - OID)",
                "name": "String"
            },
            "practiceSettingCode": {
                "code": "String",
                "codingScheme": "(String - OID)",
                "name": "String"
            },
            "typeCode": {
                "code": "String",
                "codingScheme": "(String - OID)",
                "name": "String"
            },
            "confidentialityCode": {
                "code": "String",
                "name": "String"
            }
        }
    ]
}

In the response, the elements homeCommunityId, repositoryUniqueId, and documentUniqueId are essential for retrieving documents through the Responding Gateway. These values should already exist within your system, and your document retrieval algorithm should be designed to use them to locate the requested document. This ensures a seamless and efficient process for retrieving healthcare documents from your system when interacting with OneRecord API and the healthcare interoperability networks.

For example, the following is a sample response when a document is found:

{
    "messageId": "123456789",
    "documents": [
        {
            "documentUniqueId": "1e7d85ed-aabe-43cf-94ca-2388a3e33f23",
            "repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
            "homeCommunityId": "2.16.840.1.113883.3.7080.2.4.1003.101",
            "patientIdentifier": "OneRecord-Test-Patient-101",
            "title": "Query for Documents Test Document D-1",
            "comments": "This is the comment",
            "creationTime": "20090513",
            "serviceStartTime": "20070315",
            "serviceStopTime": "20070415",
            "hash": "abc100",
            "size": 100,
            "languageCode": "en-us",
            "status": "Approved",
            "availability": "Online",
            "mimeType": "text/xml",
            "type": "OnDemand",
            "authorInstitution": "ONC Validation^^^^^^^^^2.16.840.1.113883.3.7080.2.4.1003.101",
            "authorPerson": "^Hunter^Adam^^^",
            "legalAuthenticator": "^Welby^Marcus^^^Dr^MD",
            "typeCode": {
                "code": "28619-5",
                "codingScheme": "2.16.840.1.113883.6.1",
                "name": "Ophthalmology Studies"
            },
            "documentClass": {
                "code": "34133-9",
                "codingScheme": "2.16.840.1.113883.6.1",
                "text": "Ophthalmology Studies"
            },
            "confidentialityCode": {
                "code": "N",
                "name": "Normal"
            },
            "formatCode": {
                "code": "urn:ihe:pcc:edr:2007",
                "codingScheme": "2.16.840.1.113883.3.88.12.80.73",
                "name": "Emergency Department Referral (EDR)"
            },
            "healthcareFacilityTypeCode": {
                "code": "36125001",
                "codingScheme": "2.16.840.1.113883.6.96",
                "name": "Hospital-trauma center"
            },
            "practiceSettingCode": {
                "code": "408478003",
                "codingScheme": "2.16.840.1.113883.6.96",
                "name": "Critical care medicine"
            }
        }
    ]
}

Here is a simplified version of the above response showing only the essential fields:

{
    "documents": [
        {
            "documentUniqueId": "1e7d85ed-aabe-43cf-94ca-2388a3e33f23",
            "repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
            "patientIdentifier": "OneRecord-Test-Patient-101",
            "title": "Query for Documents Test Document D-1",
            "creationTime": "20090513",
            "mimeType": "text/xml",
            "type": "OnDemand",
            "authorInstitution": "ONC Validation^^^^^^^^^2.16.840.1.113883.3.7080.2.4.1003.101",
            "authorPerson": "^Hunter^Adam^^^",
            "typeCode": {
                "code": "28619-5",
                "codingScheme": "2.16.840.1.113883.6.1",
                "name": "Ophthalmology Studies"
            }
        }
    ]
}

The following is a sample response when no documents are found:

{
    "documents": []
}

You can also exclude the documents array and return an error message like this:

{
    "status": "FAILED",
    "error": "No documents found"
}

In this example, the "status" and "error" fields are optional and are actually ignored by OneRecord API, but they may be useful for your internal logging and debugging purposes. The exclusion of the "documents" array or an empty "documents" array is sufficient to indicate that no matching documents were found.

Supporting Document Retrieval

Once document identifiers have been obtained through the Document Query endpoint, they can be used to retrieve the raw data for any of those documents. A single document retrieval request can contain instructions to retrieve one or multiple documents, so it's essential that your endpoint responds with data for all requested documents.

GET https://<your-app-url>/<path-for your-document-retrieve-endpoint>

{
    "initiatorRequestId": "[optional-String]",
    "documents": [
        {
            "documentUniqueId": "String",
            "repositoryUniqueId": "String (OID format)",
            "homeCommunityId": "String (OID format)"
        }
    ],
    "network": {
        "name": "[Carequality|eHealth Exchange]",
        "purposeOfUse": "String",
        "initiatingOrganization": {
            "name": "String",
            "identifier": "String (OID format)"
        },
        "initiatingUser": {
            "name": "String",
            "email": "String"
        }
    }
}

For example, here is a sample request body for a document retrieve:

{
    "documents": [
        {
            "documentUniqueId": "1e7d85ed-aabe-43cf-94ca-2388a3e33f23",
            "repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
            "homeCommunityId": "2.16.840.1.113883.3.7080.2.4.1003.101"
        }
    ],
    "network": {
        "respondingOrganization": {
            "name": "OneRecord",
            "identifier": "2.16.840.1.113883.3.7080.1.4.1001.101"
        }
    }
}

Your endpoint should support returning the document(s) in the following format:

{
    "messageId": "[optional-String]",
    "documents": [
        {
            "documentUniqueId": "String",
            "repositoryUniqueId": "String (OID format)",
            "homeCommunityId": "String (OID format)",
            "content": "[base64 encoded string]"
        }
    ]
}

For example, the following is a sample response when a document is retrieved:

{
    "documents": [
        {
            "documentUniqueId": "1e7d85ed-aabe-43cf-94ca-2388a3e33f23",
            "repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
            "homeCommunityId": "2.16.840.1.113883.3.7080.2.4.1003.101",
            "content": "U2FtcGxlIGRvY3VtZ...W50IGNvbnRlbnQ="
        }
    ]
}

The "content" property in the response contains a base64 encoded string that holds the data for the medical document. Once decoded, the content of the document may include CDA data in an XML format, PDF, images, or various other document types. Make sure your development team has implemented an efficient and reliable algorithm for retrieving and serving these documents as base64 encoded strings in response to OneRecord API requests. This will ensure seamless interaction between your system and the healthcare interoperability networks, ultimately providing the necessary medical data to authorized parties.

The following is a sample response when no documents could be retrieved:

{
    "documents": []
}

You can also exclude the documents array and return an error message like this:

{
    "status": "FAILED",
    "error": "Error retrieving document(s)"
}

In this example, the "status" and "error" fields are optional and are actually ignored by OneRecord API, but they may be useful for your internal logging and debugging purposes. The exclusion of the "documents" array or an empty "documents" array is sufficient to indicate the document(s) could not be retrieved.

Wrapping Up

This guide has demonstrated how OneRecord API simplifies the integration process with vast and complex networks like Carequality and CommonWell, providing a streamlined path for accessing patient records across participating communities. By leveraging OneRecord API, developers can efficiently connect to these networks, enabling a wide reach into a growing number of healthcare communities both now and in the future. For more specific details on Carequality and CommonWell, please refer to the Partner Networks Page