Demographics Network Query

Suggest Edits

First, a few basics

Now that we have the JWT from the previous setup step, let's query CommonWell and Carequality for documents. It is important to note that each network/framework has differences in how they work. We won't go into the details in this guide outside of what you need to understand in order to successfully complete a test.

The main difference is that CommonWell requires a patient to be registered with the network prior to any successful document query and document retrieve request messages can be sent. The remainder of the flow - Query for Documents and Retrieve Document(s) - are the same for both networks.

Oh! We should also mention that Carequality is a point to point connection whereas CommonWell is a broker model, but let's not digress on that in this guide - you can read more about how they work in our Interoperability 101 section.

Test Patient Setup

👍

Step 1

Configure your test patient.

Since this flow will actually query out to BOTH CommonWell and Carequality and there is not a common test patient available in both networks, we have provided two test patients for your testing pleasure. When you execute each transaction be sure to change the body params to the appropriate patient information.

CommonWell Test Patient

{
  "firstname": "Pedro",
  "lastname": "Martinez",
  "gender": "M",
  "dob": "1975-11-11",
  "homephone": "3035527394",
  "streetaddress": "123 Main St",
  "city": "Covington",
  "state": "WA",
  "zip": "98042",
  "id": "8f0ca843-c2db-4124-8816-da5b8eab1fcb"
}

Carequality Test Patient

{
  "firstname": "Pedro",
  "lastname": "Martinez",
  "gender": "M",
  "dob": "1975-11-11",
  "homephone": "3035527394",
  "streetaddress": "123 Main St",
  "city": "Covington",
  "state": "WA",
  "zip": "98042",
  "id": "8f0ca843-c2db-4124-8816-da5b8eab1fcb"
}

Register Patient

👍

Step 2

Register your test patient (CommonWell only).

In CommonWell, before a search for a patient's documents can be successfully kicked off, that person must be registered within the CommonWell network. The Register Patient step is where this happens. If the person is already registered a message will be returned to the registerer with an appropriate message. There is no harm in "repeat registrations" in a test environment. In production environments you will want to consider your strategy a little more carefully to avoid unnecessary service calls.

Basic REST Implementation

POST: https://stage.integrator.onerecord.com/integrator/v1/patient/register

{
  "id": "8f0ca843-c2db-4124-8816-da5b8eab1fcb",
  "firstname": "Pedro",
  "lastname": "Martinez",
  "dob": "1975-11-11",
  "gender": "M",
  "zip": "98042"
}

CLI Implementation

curl --request POST \
  --url https://stage.integrator.onerecord.com/integrator/v1/patient/register \
  --header 'Accept: */*' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer [provided jwt]' \  
  --data '{"id": "8f0ca843-c2db-4124-8816-da5b8eab1fcb","firstname":"Pedro","lastname":"Martinez","dob":"1975-11-11","gender":"M","zip":"98042"}'

Query for Documents

👍

Step 3

Query for your test patient's healthcare documents.

Querying for a list of documents is the next step in the flow. This will return a list of documents available for retrieval by the caller. The document list will contain metadata needed for use in the subsequent Document Retrieve step.

We will use a sample test patient Pedro Martinez who has already been configured in the system with test documents. The transaction here is a post and includes the patient data shown below.

Basic REST Implementation

POST: https://stage.integrator.onerecord.com/integrator/v1/patient/documents

{
  "id": "8f0ca843-c2db-4124-8816-da5b8eab1fcb",
  "firstname": "Pedro",
  "lastname": "Martinez",
  "dob": "1975-11-11",
  "gender": "M",
  "zip": "98042"
}

CLI Implementation

curl --request POST \
  --url https://stage.integrator.onerecord.com/integrator/v1/patient/documents \
  --header 'Accept: */*' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer [provided jwt]' \  
  --data '{"id": "8889143389765","firstname":"Pedro","lastname":"Martinez","dob":"1975-11-11","gender":"M","zip":"98042"}'

Try this request using our API REFERENCE: /patient/documents

This is a test patient's document results.

{
    "gateways": [
        {
            "communityId": null,
            "community": "CareQuality",
            "documents": [],
            "errorCode": "3100",
            "errorDescription": "Patient query failure",
            "id": null,
            "queryDocumentExecutionTime": null,
            "state": "COMPLETE",
            "totalDocs": null
        },
        {
            "communityId": "2.16.840.1.113883.3.3330.12",
            "community": "CommonWell",
            "documents": [
                {
                    "structuredDocId": "2.16.840.1.113883.3.3330.8889429.1433.2^89765..1",
                    "repositoryUniqueId": "2.16.840.1.113883.3.3330.8889429.1433.2",
                    "classCode": {
                        "code": null,
                        "codingScheme": null,
                        "names": []
                    },
                    "name": "OneRecord-OrgB-1433 Summarization Of Episode Note",
                    "authorInstitution": "OneRecord-OrgB-1433"
                }
            ],
            "errorCode": "3202",
            "errorDescription": "Document query partial success",
            "id": null,
            "queryDocumentExecutionTime": "1.046",
            "state": "DOCRETRIEVES",
            "totalDocs": "1"
        }
    ],
    "id": null
}

Upon getting the response for the test patient, we extract the document id (structuredDocId), repository id (repositoryUniqueId), community name (community) and community id (communityId). We will then pipe those values into a query to retrieve one or more documents.

Retrieve Document(s)

👍

Step 4

Select documents and retrieve!

In our example we only retrieved one document from CommonWell. Regardless, /document/retrieve is the proper endpoint to get the contents of a single doc or multiple docs. You would simply add more elements to the JSON array (see example below) to retrieve multiple documents.

Basic REST Implementation

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

[
  {
    "community": "CommonWell",
    "communityId": "2.16.840.1.113883.3.3330.12",   
    "documentId": "2.16.840.1.113883.3.3330.8889429.1433.2^89765..1",
    "repositoryUniqueId": "2.16.840.1.113883.3.3330.8889429.1433.2"
  }
]

CLI Implementation

curl --request POST \
  --url https://stage.integrator.onerecord.com/integrator/v1/document/retrieve \
  --header 'Accept: */*' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer [provided jwt]' \  
  --data '{"documents":[{"communityId":"2.16.840.1.113883.3.3330.12","documentId":"2.16.840.1.113883.3.3330.8889429.1433.2^89765..1","repositoryUniqueId":"2.16.840.1.113883.3.3330.8889429.1433.2"}]}'

Try this request using our API REFERENCE: /document/retrieve

In the response body we get back base64 encoded XML which we can transform to human readable output.

[
    {
        "availabilityStatus": null,
        "structuredDocId": "2.16.840.1.113883.3.3330.8889429.1433.2^89765..1",
        "repositoryUniqueId": "2.16.840.1.113883.3.3330.8889429.1433.2",
        "homeCommunityId": "2.16.840.1.113883.3.3330.12",
        "body": "PD94bWwtc3R5bGVzaGVldCB0eXBlPSJ0ZXh0L3hzbCIgaHJlZj0iQ0RBX0FSUkEyLnhzbCI/PjxDbGluaWNhbERvY3VtZW50IHhtbG5zOnNkdGM9InVybjpobDctb3JnOnNkdGMiIHhtbG5zOnZvYz0idXJuOmhsNy1vcmc6djMvdm9jIiB4bWxuczp4c2k9Imh0dHA6Ly93d3cudzMub3JnLzIwMDEvWE1MU2NoZW1hLWluc3RhbmNlIiB4bWxucz0idXJuOmhsNy1vcmc6djMiIHhzaTpzY2hlbWFMb2NhdGlvbj0idXJuOmhsNy1vcmc6djMgaHR0cDovL3hyZWcyLm5pc3QuZ292OjgwODAvaGl0c3BWYWxpZGF0aW9uL3NjaGVtYS9jZGFyMmMzMi9pbmZyYXN0cnVjdHVyZS9jZGEvQzMyX0NEQS54c2QiPjxyZWFsbUNvZGUgY29kZT0iVVMiIC8+PHR5cGVJZCBleHRlbnNpb249IlBPQ0RfSEQwMDAwNDAiIHJvb3Q9IjIuMTYuODQwLjEuMTEzODgzLjEuMyIgLz48dGVtcGxhdGVJZCByb290PSIyLjE2Ljg0MC4xLjExMzg4My4xMC4yMC4yMi4xLjEiIC8+...==",
        "errors": null
    }
]

Parse and Render Documents

👍

Step 6

Parse and render documents, and incorporate into your workflow.

Now that we have retrieved the document from CommonWell using our example patient, we can extract the base64 encoded document content and decode it. This can be done using an online decoder for purposes of this guide, but you should have your own built in solution that is properly secured for dealing with PHI. Below is a portion of the content after a base64 decode. To see the full example take a look at our Examples page.

First in XML.

<?xml-stylesheet type="text/xsl" href="CDA_ARRA2.xsl"?>
<ClinicalDocument
	xmlns:sdtc="urn:hl7-org:sdtc"
	xmlns:voc="urn:hl7-org:v3/voc"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="urn:hl7-org:v3" xsi:schemaLocation="urn:hl7-org:v3 http://xreg2.nist.gov:8080/hitspValidation/schema/cdar2c32/infrastructure/cda/C32_CDA.xsd">
	<realmCode code="US" />
	<typeId extension="POCD_HD000040" root="2.16.840.1.113883.1.3" />
	<templateId root="2.16.840.1.113883.10.20.22.1.1" />
	<templateId root="2.16.840.1.113883.10.20.22.1.2" />
	<id root="2.16.840.1.113883.3.3330.8889429.1433.2" extension="2.16.840.1.113883.3.3330.8889429.1433.2^89765..1" />
	<code codeSystemName="LOINC" codeSystem="2.16.840.1.113883.6.1" code="34133-9" displayName="Summarization of episode note"></code>
	<title>OneRecord-OrgB-1433 Summarization Of Episode Note</title>
	<effectiveTime value="20130222094143-0500" />
	<confidentialityCode codeSystem="2.16.840.1.113883.5.25" code="N" />
	<languageCode code="en-US" />
	<recordTarget>
		<patientRole>
			<id extension="89765" root="2.16.840.1.113883.3.3330.8889429.1433.2" />
			<addr use="HP">
				<streetAddressLine>3475 Oak Place</streetAddressLine>
				<city>Arvada</city>
				<state>CO</state>
				<postalCode>38063</postalCode>
			</addr>
			<telecom value="tel:+1-(720)239-4800" use="HP" />
			<patient>
				<name use="L">
					<given>Stephen</given>
					<family>Pujols1433</family>
				</name>
				<administrativeGenderCode codeSystem="2.16.840.1.113883.5.1" code="F" displayName="Female"></administrativeGenderCode>
				<birthTime value="19950929" />
				<raceCode codeSystemName="Race and Ethnicity - CDC" codeSystem="2.16.840.1.113883.6.238" code="2106-3" displayName="White"></raceCode>
				<ethnicGroupCode codeSystemName="Race and Ethnicity - CDC" codeSystem="2.16.840.1.113883.6.238" code="2186-5" displayName="Not Hispanic or Latino"></ethnicGroupCode>
				<languageCommunication>
					<languageCode nullFlavor="NI" />
				</languageCommunication>
			</patient>
		</patientRole>
	</recordTarget>
    .
    .
    .
    .
		<structuredBody>
			<component>
				<section>
					<templateId root="2.16.840.1.113883.10.20.22.2.6.1" />
					<code codeSystemName="LOINC" codeSystem="2.16.840.1.113883.6.1" code="48765-2" displayName="Allergies, Adverse Reactions, Alerts"></code>
					<title>Allergies and Adverse Reactions</title>
					<text>
						<table width="100%" border="1">
							<thead>
								<tr>
									<th>Alert</th>
									<th>Type</th>
									<th>Reactions</th>
									<th>Severity</th>
									<th>Status</th>
								</tr>
							</thead>
							<tbody>
								<tr>
									<td ID="alert1">Aspirin drug allergy</td>
									<td ID="alerttype1">drug allergy</td>
									<td>
										<list listType="ordered">
											<item ID="reaction1">Nausea</item>
										</list>
									</td>
									<td />
									<td ID="alertstatus1">active</td>
								</tr>
								<tr>
									<td ID="alert2">Penicillin G drug allergy</td>
									<td ID="alerttype2">drug allergy</td>
									<td>
										<list listType="ordered">
											<item ID="reaction2">Hives</item>
										</list>
									</td>
									<td />
									<td ID="alertstatus2">active</td>
								</tr>
							</tbody>
						</table>
					</text>
					<entry typeCode="DRIV">
						<act classCode="ACT" moodCode="EVN">
							<templateId root="2.16.840.1.113883.10.20.22.4.30" />
							<id root="ID4gds-17jps1rk8" />
							<code codeSystemName="LOINC" codeSystem="2.16.840.1.113883.6.1" code="48765-2" displayName="Allergies, Adverse Reactions, Alerts"></code>
							<statusCode code="active" />
							<effectiveTime>
								<low nullFlavor="UNK" />
								<high nullFlavor="UNK" />
							</effectiveTime>
							<entryRelationship inversionInd="false" typeCode="SUBJ">
								<observation classCode="OBS" moodCode="EVN">
									<templateId root="2.16.840.1.113883.10.20.22.4.7" />
									<id root="ID4gds-17jps1rk8" />
									<code codeSystemName="ActCode" codeSystem="2.16.840.1.113883.5.4" code="ASSERTION" displayName="Assertion"></code>
									<statusCode code="completed" />
									<effectiveTime>
										<high nullFlavor="UNK" />
									</effectiveTime>
									<value codeSystemName="SNOMED CT" codeSystem="2.16.840.1.113883.6.96" xsi:type="CD" code="416098002" displayName="drug allergy"></value>
									<author>
										<time value="20130219133933-0500" />
										<assignedAuthor>
											<id nullFlavor="NA" />
											<addr nullFlavor="NI" />
											<telecom nullFlavor="NI" />
											<assignedPerson>
												<name>
													<given>INSTALL A</given>
													<family>HBOC</family>
												</name>
											</assignedPerson>
    .
    .
    .
    .
		</structuredBody>
	</component>
</ClinicalDocument>

Also in JSON

{
   "@schemaLocation": "urn:hl7-org:v3 http://xreg2.nist.gov:8080/hitspValidation/schema/cdar2c32/infrastructure/cda/C32_CDA.xsd",
   "realmCode": {
      "@code": "US"
   },
   "typeId": {
      "@extension": "POCD_HD000040",
      "@root": "2.16.840.1.113883.1.3"
   },
   "templateId": [
      {
         "@root": "2.16.840.1.113883.10.20.22.1.1"
      },
      {
         "@root": "2.16.840.1.113883.10.20.22.1.2"
      }
   ],
   "id": {
      "@root": "2.16.840.1.113883.3.3330.8889429.1433.2",
      "@extension": "2.16.840.1.113883.3.3330.8889429.1433.2^89765..1"
   },
   "code": {
      "@codeSystemName": "LOINC",
      "@codeSystem": "2.16.840.1.113883.6.1",
      "@code": "34133-9",
      "@displayName": "Summarization of episode note"
   },
   "title": "OneRecord-OrgB-1433 Summarization Of Episode Note",
   "effectiveTime": {
      "@value": "20130222094143-0500"
   },
   "confidentialityCode": {
      "@codeSystem": "2.16.840.1.113883.5.25",
      "@code": "N"
   },
   "languageCode": {
      "@code": "en-US"
   },
   "recordTarget": {
      "patientRole": {
         "id": {
            "@extension": "89765",
            "@root": "2.16.840.1.113883.3.3330.8889429.1433.2"
         },
         "addr": {
            "@use": "HP",
            "streetAddressLine": "3475 Oak Place",
            "city": "Arvada",
            "state": "CO",
            "postalCode": "38063"
         },
         "telecom": {
            "@value": "tel:+1-(720)239-4800",
            "@use": "HP"
         },
         "patient": {
            "name": {
               "@use": "L",
               "given": "Stephen",
               "family": "Pujols1433"
            },
            "administrativeGenderCode": {
               "@codeSystem": "2.16.840.1.113883.5.1",
               "@code": "F",
               "@displayName": "Female"
            },
            "birthTime": {
               "@value": "19950929"
            },
            "raceCode": {
               "@codeSystemName": "Race and Ethnicity - CDC",
               "@codeSystem": "2.16.840.1.113883.6.238",
               "@code": "2106-3",
               "@displayName": "White"
            },
            "ethnicGroupCode": {
               "@codeSystemName": "Race and Ethnicity - CDC",
               "@codeSystem": "2.16.840.1.113883.6.238",
               "@code": "2186-5",
               "@displayName": "Not Hispanic or Latino"
            },
            "languageCommunication": {
               "languageCode": {
                  "@nullFlavor": "NI"
               }
            }
         }
      }
   },
      .
      .
      .
      .
   "component": {
      "structuredBody": {
         "component": [
            {
               "section": {
                  "templateId": {
                     "@root": "2.16.840.1.113883.10.20.22.2.6.1"
                  },
                  "code": {
                     "@codeSystemName": "LOINC",
                     "@codeSystem": "2.16.840.1.113883.6.1",
                     "@code": "48765-2",
                     "@displayName": "Allergies, Adverse Reactions, Alerts"
                  },
                  "title": "Allergies and Adverse Reactions",
                  "text": {
                     "table": {
                        "@width": "100%",
                        "@border": "1",
                        "thead": {
                           "tr": {
                              "th": [
                                 "Alert",
                                 "Type",
                                 "Reactions",
                                 "Severity",
                                 "Status"
                              ]
                           }
                        },
                        "tbody": {
                           "tr": [
                              {
                                 "td": [
                                    {
                                       "@ID": "alert1",
                                       "#text": "Aspirin drug allergy"
                                    },
                                    {
                                       "@ID": "alerttype1",
                                       "#text": "drug allergy"
                                    },
                                    {
                                       "list": {
                                          "@listType": "ordered",
                                          "item": {
                                             "@ID": "reaction1",
                                             "#text": "Nausea"
                                          }
                                       }
                                    },
                                    null,
                                    {
                                       "@ID": "alertstatus1",
                                       "#text": "active"
                                    }
                                 ]
                              },
                              {
                                 "td": [
                                    {
                                       "@ID": "alert2",
                                       "#text": "Penicillin G drug allergy"
                                    },
                                    {
                                       "@ID": "alerttype2",
                                       "#text": "drug allergy"
                                    },
                                    {
                                       "list": {
                                          "@listType": "ordered",
                                          "item": {
                                             "@ID": "reaction2",
                                             "#text": "Hives"
                                          }
                                       }
                                    },
                                    null,
                                    {
                                       "@ID": "alertstatus2",
                                       "#text": "active"
                                    }
                                 ]
                              }
                           ]
                        }
                     }
                  },
                  "entry": [
                     {
                        "@typeCode": "DRIV",
                        "act": {
                           "@classCode": "ACT",
                           "@moodCode": "EVN",
                           "templateId": {
                              "@root": "2.16.840.1.113883.10.20.22.4.30"
                           },
                           "id": {
                              "@root": "ID4gds-17jps1rk8"
                           },
                           "code": {
                              "@codeSystemName": "LOINC",
                              "@codeSystem": "2.16.840.1.113883.6.1",
                              "@code": "48765-2",
                              "@displayName": "Allergies, Adverse Reactions, Alerts"
                           },
                           "statusCode": {
                              "@code": "active"
                           },
                           "effectiveTime": {
                              "low": {
                                 "@nullFlavor": "UNK"
                              },
                              "high": {
                                 "@nullFlavor": "UNK"
                              }
                           },
                           "entryRelationship": {
                              "@inversionInd": "false",
                              "@typeCode": "SUBJ",
                              "observation": {
                                 "@classCode": "OBS",
                                 "@moodCode": "EVN",
                                 "templateId": {
                                    "@root": "2.16.840.1.113883.10.20.22.4.7"
                                 },
                                 "id": {
                                    "@root": "ID4gds-17jps1rk8"
                                 },
                                 "code": {
                                    "@codeSystemName": "ActCode",
                                    "@codeSystem": "2.16.840.1.113883.5.4",
                                    "@code": "ASSERTION",
                                    "@displayName": "Assertion"
                                 },
                                 "statusCode": {
                                    "@code": "completed"
                                 },
                                 "effectiveTime": {
                                    "high": {
                                       "@nullFlavor": "UNK"
                                    }
                                 },
                                 "value": {
                                    "@codeSystemName": "SNOMED CT",
                                    "@codeSystem": "2.16.840.1.113883.6.96",
                                    "@type": "CD",
                                    "@code": "416098002",
                                    "@displayName": "drug allergy"
                                 },
                                 "author": {
                                    "time": {
                                       "@value": "20130219133933-0500"
                                    },
                                    "assignedAuthor": {
                                       "id": {
                                          "@nullFlavor": "NA"
                                       },
                                       "addr": {
                                          "@nullFlavor": "NI"
                                       },
                                       "telecom": {
                                          "@nullFlavor": "NI"
                                       },
                                       "assignedPerson": {
                                          "name": {
                                             "given": "INSTALL A",
                                             "family": "HBOC"
                                          }
                                       },
      .
      .
      .
      .
                                   
         ]
      }
   }
}

Wrap Up

Congrats - you have just completed the Demographics Network Query flow! We started with ensuring our person/patient was properly registered, then performed a document query, and finally a document retrieve, extracting the document through a base64 decode.

From here you can start thinking about how to embed these calls into your own solutions. Reach out to us about getting an API Key if you haven't already!

Updated over 1 year ago