Request patient documents

Who can use this how-to

  • Starter package customers using digital record retrieval
  • Existing customers using digital record retrieval
  • Existing customers with a direct connection to Carequality (i.e., without digital record retrieval)

After successfully searching and locating patient records at a given organization, you have two options to request relevant patient 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.

Use curl for technical validation

You can copy the code examples we provide and send the test requests with curl (learn more about curl) instead of Postman. Keep in mind though that you need to remove the comments from the code examples (starting with //) and replace any variables (e.g., {{variable here}}) to use them. Also, note that some of the code examples are abbreviated, so be mindful of that if you're copying them for your own use.

Option 1: Request one patient summary

  1. Using Postman or curl, send the ClinicalSummary.PatientQuery request with 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).
  2. If the request is successful, you receive a synchronous ClinicalSummary.PatientQueryResponse with the latest patient summary document (i.e., a snapshot of the patient’s current chart).

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. 

  1. Using Postman or curl, send the ClinicalSummary.DocumentQuery request with 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).
  2. If the request is successful, you receive a synchronous ClinicalSummary.DocumentQueryResponse with a document list with an identifier, type, and date for each document so that you can identify the most relevant documents.
  3. Using Postman or curl, send the ClinicalSummary.DocumentGet request with the relevant metadata, like the document ID and type (from the response in the previous steps) 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.

  4. If the request is successful, you receive a synchronous ClinicalSummary.DocumentGetResponse with the relevant document of interest. The response 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.

Next steps