2. Request patient records and documents

To obtain patient records, you first need to identify organizations that have seen your patient. Then you can request any documents for that patient from each of those organizations.

Each query contains required metadata fields that identify the requesting user and their organization, specify the purpose of use, and direct the request to the target organization. These fields exist within the Meta section of the query.

Field
Description
Notes
Meta.Destinations.ID
A universally unique identifier (UUID) for the destination you wish to search.
This ID is different for staging and production environments.
For most patient searches, this is a Redox destination within record locator service.
For document searches, this is a Carequality destination.
For responding with information about your patients, this is your own document repository.
Meta.FacilityCode
The OID of the organization you wish to query.
This isn't necessary for patient searches with record locator service.
Meta.Extensions.organization-name
The name of the organization running the query.
Generally, this is the name of your organization or the covered entity that you are providing services for.
Meta.Extensions.sender-organization-id
The organizational OID to identify your organization as the one sending the request.
Meta.Extensions.user-id
Contains either the name of the user sending the request or the name of the relevant provider.
This should be a human-readable identifier and is required for audit purposes.
The provider’s name should still be populated when an automated process runs the query. For example, a provider may have an automated process triggered after completing a patient visit, in which case, the query runs in the background on the provider’s behalf.
Meta.Extensions.user-role
Defines the role of the user sending the request.
You must use a SNOMED value for this field. Check out the US Health Information Knowledgebase for a list of available SNOMED values.
Meta.Extensions.purpose-of-use
The purpose of use for this request (e.g., Treatment).
You must qualify for a "Treatment" purpose of use when using digital record retrieval.

Meta fields are required

The Meta fields are required on every step of every request to Carequality. If you do not include these fields, you receive an authentication error in return.

You can see how the Meta fields are populated in the example below.

Locate records for your patient

You have two options for finding and obtaining a patient’s record: 

  1. Search for a patient using the Redox Record Locator Service: If you don’t know where the patient is located or you believe the patient exists in multiple locations, you can ask Redox to provide a list of possibilities. Then you can skip right to getting documents. This is the the most common option since it allows you to identify all of the places where a patient’s record may exist.
  2. Search for a patient with your own location search: If you have a static list of locations you wish to search or know exactly which organizations have records for the patient, you can search those specific organizations or locations directly. Keep in mind that this means you can only search one organization at a time.

Redox patient ID

For every patient, your system assigns a local patient ID within your system, which is also used within your data on demand repository. The local ID is assigned by your system and it may or may not be unique.

We also create a network patient ID for the same patient. The network ID is a unique identifier assigned by Redox to identify the document within the Framework.

As a result, the patient ID in the data on demand repository isn't the same as the patient ID in the Framework. To find the network ID for a patient, send a PatientSearch.Query with the patient demographics to the Redox gateway: 2.16.840.1.113883.3.6147.458.2.

Learn how to search for a patient.

If you want to know where you can get patient records from, explore a list of active Carequality participants with this search tool.

Option 1: Search by patient with Record Locator Service

This popular option relies on Redox Record Locator Service to do the heavy lifting for you.

Step 1: Search for a patient

First, we use your PatientSearch.Query to look for Carequality participants within the same area as your organization and the patient’s home address (if supplied). Next, we leverage results from other Redox client searches so we can go beyond the search area, if possible. 

More specifically, the PatientSearch.Query through the Record Locator Service takes a patient’s demographics and returns a Redox Patient ID. The response also returns a list of locations where the patient exists—along with the patient’s localized IDs at each location, which we validate.

Redox Patient ID

The Redox Patient ID is persistent and can be linked to your patient locally. This means you can skip the initial PatientSearch.Query if you already have the Redox Patient ID.

If the patient demographics change or you receive an HTTP status 404 from the PatientSearch.LocationQuery, you should repeat the PatientSearch.Query with the patient’s updated demographics to get the correct Redox Patient ID.

Step 2: Find all locations a patient has visited

Once you have the Redox Patient ID from the previous step, you retrieve the locations where their record exists with the PatientSearch.LocationQuery.

In the response, the Meta.Extensions.task-status.string field contains a status of either Active or Success.

Status
Definition
Results
Active
The process is asynchronously collecting locations.
The Patients array populates with any partial results as they become available.
Success
The process has completed and all possible locations were found.
Any available results have been returned.
If the Patients array is empty, it means no patients were found.

The response waits up to 10 seconds to reach a Success state. If unable to reach Success in that time, the response retains an Active status. You can retry the exact request repeatedly until it reaches a Success state.

Review your search results later

To review the results of your search again later, you can provide the value returned in Meta.Extensions.task-id.string on subsequent requests.

Same demographics, same results

If you run a new search with the same patient demographics within a 24-hour period, you see the same results. Record Locator Service doesn't trigger a new search to your connections unless you have new or modified patient demographics.

If you know exactly where a patient was seen previously, you can search for a patient at an individual organization. If you want to search multiple organizations, you must search them one at a time.

If you already have a list of organizations and their respective OIDs to search with, you can skip this step.

If you don’t already have an ID for the organizations to search, you must first send the Organization.Query request. With this query, you search by ZIP code radius or organization name. From the results list, you can select one or all of these organizations to then run a patient search.

If the request is successful, you receive a synchronous Organization.QueryResponse with the relevant organization results.

Check if an organization has seen a patient

Now that you have an organization to search, use the PatientSearch.Query to see if that organization has your patient’s records. You must use the organization’s OID in each request.

Where to find the OID

The OID is found in the FacilityCode field of the Organization.QueryResponse that you received in the previous step.

In the body of the request, include the patient’s demographics. Don't forget, you can check out the Appendix for all of our test patient data used in these examples.

If your search matches a patient at the given organization, the response returns the patient’s identifier and additional details. If a patient isn’t found, the response returns an empty array.

The response may not look exactly like this, but should be similar.

Request patient documents

Once you locate records for your patient, you have two options when requesting documents:

  1. Request one patient summary: Typically, the simplest option is to request a generic patient summary directly. 
  2. Retrieve a document list and select relevant documents: If you can select documents of interest within your own UI, you can retrieve a full list of available documents and select the specific documents that are of interest.

The returned documents from either option follow a standard format (Consolidated-Clinical Document Architecture, or C-CDA) and include several sections of information related to the patient’s demographics, encounters, medications, diagnoses, allergies, and more. Check the Carequality FAQ for more details about which elements of the C-CDA document are required or optional.

Different organization, different data

Different organizations may include varying amounts of information or specificity, or they may use different codesets to represent the data. We simply pass the data as we receive it from the responding organization.

Option 1: Request one patient summary

With this option, you can use the ClinicalSummary.PatientQuery to receive the latest patient summary document (i.e., a snapshot of the patient’s current chart).

In the body of the request, you must include the relevant metadata, like the patient’s ID and ID Type (from the PatientSearch response) and the organization OID (which goes in the Meta.FacilityCode field).

If the request is successful, you receive a synchronous ClinicalSummary.PatientQueryResponse with the relevant results.

Option 2: Retrieve multiple documents through your own UI

With this option, you receive a full list of documents related to the patient. Then, you can choose from the list in a separate step. 

Step 1: Retrieve a document list

Use the ClinicalSummary.DocumentQuery to return a document list with an identifier, type, and date for each document so that you can identify the most relevant documents.

In the body of the request, you must include the relevant metadata, like the patient’s ID and ID Type (from the PatientSearch response) and the organization OID (which goes in the Meta.FacilityCode field).

If the request is successful, you receive a synchronous ClinicalSummary.DocumentQueryResponse with the relevant results.

Step 2: Get a document

Use the ClinicalSummary.DocumentGet to retrieve a document of interest from the document list you received in the previous step.

In the body of the request, you must include the relevant metadata, like the document ID and type (from the ClinicalSummary.DocumentQueryResponse results) and the organization OID (which goes in the Meta.FacilityCode field).

Less is more

Documents can only be retrieved one by one. We recommend retrieving only the most relevant documents, not every document on the list.

You can see an example below with the same data from the previous step.

If the request is successful, you receive a synchronous ClinicalSummary.DocumentGetResponse with the relevant results.

A Carequality response to DocumentGet always includes both the raw XML document data from the responding organization and our translated JSON, so you can easily parse and store the patient’s information. The translated JSON matches the Clinical Summary.VisitQueryResponse data model. Learn more about the response format.

Alternatively, some organizations use the raw data with one of many public libraries to translate the XML into a readable UI.