Request patient documents with FHIR

Last updated: May 29, 2025

IMPLEMENTATION

Who can use this how-to

Existing customers using Network Onramps to connect to the Carequality Interoperability Framework
Existing customers with a direct connection to Carequality (i.e., without Redox)

After you successfully search and locate patient records at a given organization, you can request patient documents.

With FHIR®, you can pick documents of interest within your own UI. That way you can retrieve a full list of available documents and select the documents you want.

A majority of the returned documents follow a standard format (i.e., C-CDA) and include several sections of information related to the patient’s demographics, encounters, medications, diagnoses, allergies, and more. Check out required C-CDA elements.

Different organization, different data

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

Data model option

Did you know you can also do this workflow with Redox data models? Learn how to request patient documents with the Redox Data Model API.

Use curl for technical validation

You can copy our code examples and send the test requests with curl (learn more about curl) instead of Postman. If you do, remember to:

Remove the comments from the code examples (starting with //).
Replace any variables (e.g., {{variable here}}).
Add the source-id if you have multiple sources. We don’t include {{source-id}} in the code examples, so you’ll have to add them yourself. Learn about including source details.
Make sure you have a full request for your own use since some of the code examples are abbreviated.

Check out these troubleshooting guides if you run into errors:

Canada URL

If you’re operating in Canada, you have to tweak the Redox hostname slightly. Add ca in the URL like this: https://api.ca.redoxengine.com.

Use the DocumentReference_search to pick your own documents. This allows you to receive a full list of documents related to the patient. The response returns PDFs, C-CDAs, or any other documents attached to the patient record.

Then, query for any document from the list. You receive the document in both raw XML—which is useful if you have your own document renderer—and in a Redox-parsed view for any data that we can parse.

Query components

FHIR® headers for queries

Each query contains required metadata headers that identify the requesting user and their organization, specify the purpose of use, and direct the request to the target organization.

This table contains the HTTP headers for the relevant metadata when using the Redox FHIR® API to request patient documents.

Header	Description	Notes
`x-sender-organization-id`	The OID of your Carequality organization. This specifies that your organization is sending the query.	It helps to be specific if you have multiple levels within your Carequality organization. However, you can also use your organization’s top-level OID.
`x-user-id`	Either the name of the user sending the request or 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 that case, the query runs in the background on the provider’s behalf. This isn’t necessary for patient searches with record locator service.
`x-user-role`	The role of the user sending the request.	You must use a SNOMED value for this field. Check out the U.S. Health Information knowledge base for a list of available SNOMED values.
`x-purpose-of-use`	The purpose of use for this request (e.g., Treatment).	You must qualify for a “Treatment” purpose of use when using Network Onramps. If you have a different purpose of use, other Carequality participants aren't likely to respond. Remember that to be a Carequality participant, you must also push data.

FHIR® search parameters

Parameter	Description	Example
patient	The patient ID. The ID type is separated by a caret based on the result of the patient search.	681d2103-f883-4334-886b-59358580dcb1^2.16.840.1.113883.3.6147.458.2
period	The service/visit timestamps to constrain the search by. We only support equals (eq), less than, equal-to (le), and greater than, equal-to (ge). See date parameter specifications.	period=ge2025-01-01&period=le2025-03-01
date	The document creation timestamps to constrain the search by. We only support equals (eq), less than, equal-to (le), and greater than, equal-to (ge). See date parameter specifications.	date=ge2025-01-01&date=le2025-03-01
_sort	How results should be sorted. We only support sorting by date (ascending order) or -date (descending order, i.e., most recent first).	-date
_count	The number of document entries to return in the response payload.	100

Step 1: Get a document list

Using Postman or curl, send the DocumentReference_search request with the relevant search parameters. At a minimum, you have to include the patient parameter. Review the table above for more information.
Getting documents of value
It’s possible to get lots of documents that may or may not be useful to you. We recommend requesting the patient’s most recent CCD (i.e., LOINC 34133-9) and progress notes (LOINC 11506-3) from the last three months.
Be aware that responders may have different names for progress notes, like “telephone,” “office visit,” or “emergency.” You can find the document’s LOINC value in the Documents[].Type.Code for each document returned in the ClinicalSummary.documentQueryResponse.
FHIR example: Search for a document list
bash
1
curl --request POST \
2
--url https://api.redoxengine.com/fhir/R4/ceq-xca:2.16.840.1.113883.3.6147.458.2/Development/DocumentReference/_search \
3
--header 'Content-Type: application/x-www-form-urlencoded' \
4
--header 'x-purpose-of-use: TREATMENT' \
5
--header 'x-sender-organization-id: {{your_oid}}' \
6
--header 'x-user-id: {{user_human_readable_id}}' \
7
--header 'x-user-role: {{user_role}}' \
8
--data patient=681d2103-f883-4334-886b-59358580dcb1^2.16.840.1.113883.3.6147.458.2
FHIR API reference
Review the DocumentReference schema for more technical details.

If the request is successful, you receive a document list with an identifier and a type for each document so that you can identify the most relevant documents. In the example below, we only show one returned for brevity, but the example should return four if you try it out for yourself.

FHIR example: Successful response for a document list

json

1
{
2
  "resourceType": "Bundle",
3
  "type": "searchset",
4
  "total": 4,
5
  "entry": [
6
    {
7
      "resource": {
8
        "resourceType": "DocumentReference",
9
        "id": "NzVjYjRhZDQtZTVmOS00Y2QzLTg3NTAtZWI1MDUwNTIxZTBk^Mi4xNi44NDAuMS4xMTM4ODMuMy42MTQ3LjQ1OC41NTUxLjIuMS4x^dXJuOm9pZDoyLjE2Ljg0MC4xLjExMzg4My4zLjYxNDcuNDU4LjU1NTEuMi4xLjE=",
10
        "masterIdentifier": {
11
          "system": "urn:uuid:2e82c1f6-a085-4c72-9da3-8640a32e42ab",
12
          "value": "75cb4ad4-e5f9-4cd3-8750-eb5050521e0d"
13
        },
14
        "status": "current",
15
        "category": {
16
          "coding": [
17
            {
18
              "system": "2.16.840.1.113883.6.1",
19
              "code": "18842-5"
20
            }
21
          ],
22
          "text": "Progress Note"
23
        },
24
        "subject": {
25
          "type": "Patient",
26
          "identifier": [
27
            {
28
              "system": "2.16.840.1.113883.3.6147.458.2",
29
              "value": "681d2103-f883-4334-886b-59358580dcb1"
30
            }
31
          ]
32
        },
33
        "description": "Progress Note",
34
        "content": [
35
          {
36
            "attachment": {
37
              "contentType": "text/xml",
38
              "language": "en-US",
39
              "title": "Progress Note"
40
            },
41
            "format": "urn:ihe:iti:xds:2017:mimeTypeSufficient"
42
          }
43
        ],
44
        "context": {
45
          "encounter": [
46
            {
47
              "status": "planned",
48
              "facilityType": {
49
                "text": "General Medicine"
50
              },
51
              "practiceSetting": {
52
                "text": "General Medicine"
53
              }
54
            }
55
          ]
56
        }
57
      },
58
      "search": {
59
        "mode": "match"
60
      },
61
      "fullUrl": "urn:uuid:133dfc12-c77e-4f9c-8ced-039f8621ad0c"
62
    }
63
  ]
64
  ...
65
}

Step 2: Retrieve a specific document

Using Postman or curl, send the DocumentReference read request with the document ID and type (from the response in the previous step) and the organization OID.

Less is more

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

FHIR example: Retrieve a document

bash

1
curl --request GET \
2
  --url https://api.redoxengine.com/fhir/R4/ceq-xca:2.16.840.1.113883.3.6147.458.2/Development/DocumentReference/YjE2OTI2N2MtMTBjOS00ZmUzLTkxYWUtOWNrZjU3MDNlOTBs%5EMi4xNi44NDAuMS4xMTM4ODMuMy42MTQ3LjQ1OC41NTUxLjIuMS4x%5EdXJuOm9pZDoyLjE2Ljg0MC4xLjExMzg4My4zLjYxNDcuNDU4LjU1NTEuMi4xLjE= \
3
  --header 'Content-Type: application/x-www-form-urlencoded' \
4
  --header 'x-purpose-of-use: TREATMENT' \
5
  --header 'x-sender-organization-id: {{your_oid}}' \
6
  --header 'x-user-id: {{user_human_readable_id}}' \
7
  --header 'x-user-role: {{user_role}}'

If the request is successful, you receive the specified DocumentReference resource to review the document of interest. The content will always be base64-encoded and parsing isn’t performed.

FHIR example: Successful document retrieval

json

1
{
2
  "content": [
3
    {
4
      "attachment": {
5
        "contentType": "application/pdf",
6
        "data": "JVBER...JUVPRgo="
7
      }
8
    }
9
  ],
10
  "status": "current",
11
  "masterIdentifier": {
12
    "value": "2.16.840.1.113883.3.6147.458.5551.2.1.1^b169267c-10c9-4fe3-91ae-9ckf5703e90l",
13
    "system": "urn:oid:2.16.840.1.113883.3.6147.458.5551.2.1.1"
14
  },
15
  "resourceType": "DocumentReference"
16
}

Next steps

Maintain your Redox repository

Resources for onramp to Carequality with FHIR

Basic information

What are Network Onramps?
Carequality identity and organization structure
Carequality FAQ
Carequality test patients (contains patient data to use when testing)

How-to

Troubleshooting

Common Carequality errors

FHIR® is a registered trademark of Health Level Seven International (HL7) and is used with the permission of HL7. Use of this trademark does not constitute an endorsement of products/services by HL7®.