- Existing customers using Network Onramps
- 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. There are two options for this step.

- Use Redox to request the latest patient summary: Typically, the simplest option is to request a generic patient summary directly via Redox. You can perform this type of search with the Redox Data Model API.
- Pick your own docs: 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. You can perform this type of search with either the Redox Data Model API or FHIR® API.
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 out required C-CDA elements.
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.
You can copy the code examples we provide and send the test requests with curl (learn more about curl) instead of Postman. Be mindful of these things if you do:
- Remove the comments from the code examples (starting with //) and replace any variables (e.g., {{variable here}}).
- If you have multiple sources, add the source-id, which isn't included in the code examples. Learn about including source details.
- Some of the code examples are abbreviated, so make sure you have a full request for your own use.
As always, if you run into errors, check out our troubleshooting tips.
If you're operating in Canada, you must tweak the Redox hostname slightly. All you need to do is add a ca in that URL like this: https://api.ca.redoxengine.com.
Choose this option if you only want CDA documents, and you want to automatically get the most recent CDA for a patient. You receive the data back in a nice Redox-parsed view.
We don't currently support this option with the Redox FHIR® API.
This option relies on the ClinicalSummary data model.
- Using Postman or curl, send a 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).Example: Request a patient summarybash1curl \2-X POST https://api.redoxengine.com/endpoint \3-H "Content-Type: application/json" \4-H "Authorization: Bearer $API_TOKEN" \5-d '{6"Meta": {7"Extensions": {8"sender-organization-id": {9"url": "https://api.redoxengine.com/extensions/sender-organization-id",10// The OID represents the organization sending the query. You can use a top-level OID, but if there are multiple levels, it helps to be specific.11"string": "{{organization_oid}}"12},13"user-id": {14"url": "https://api.redoxengine.com/extensions/user-id",15// The user ID should be human-readable (typically name, not an ID) and change per query based on the initiating user.16"string": "{{user-name}}"17},18"user-role": {19"url": "https://api.redoxengine.com/extensions/user-role",20// Defines the role of the user identified above. This must be a SNOMED CT code.21"coding": {22"code": "{{user_role}}",23"display": "{{human-readable-name-for-code}}"24}25},26"purpose-of-use": {27"url": "https://api.redoxengine.com/extensions/purpose-of-use",28// For Carequality participants: Identifies the purpose of the query, which is almost always TREATMENT. If another purpose of use, other Carequality participants likely won't respond.29"coding": {30"code": "TREATMENT",31"display": "Treatment"32}33}34},35"DataModel": "Clinical Summary",36"EventType": "PatientQuery",37"Test": true,38"Destinations": [39{40// This is a standard Redox value that varies between environments. Use ec745338-8849-43ad-a7ce-4bc5bf1d8b89 for development environments or 628cbf79-1156-4923-b9d0-285906160ed6 for production environments.41"ID": "{{document-query-destination-id}}"42}43],44// This value represents which Carequality participant to query. For a broad search, use the organization OID-type ID from the location response. For a narrow search, use the organization OID-type ID from the organization search. The example here represents Redox.45"FacilityCode": "2.16.840.1.113883.3.6147.458.2"46},47"Patient": {48"Identifiers": [49{50// Use the identifier from the patient search response.51"ID": "{{patient-id}}",52"IDType": "{{patient-id-type}}"53}54]55}56}API reference
Review the ClinicalSummary data model schema for more technical details.
- 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).Example: Successful response for a patient summaryjson1{2"InsurancesText": "",3"Insurances": [],4"Header": {5"Document": {6"Visit": {7"Location": null,8"VisitNumber": "",9"EndDateTime": "",10"StartDateTime": ""11},12"Author": {13"Location": {14"Facility": "MADISON ANESTHESIOLOGY CONSULTANTS, LLP"15}16},17"ID": "2.16.840.1.113883.19.5^92cce54a-3a9f-634a-4d20-7e566ecc32ab",18"TypeCode": {19"AltCodes": [],20"CodeSystemName": "LOINC",21"CodeSystem": "2.16.840.1.113883.6.1",22"Name": "Summarization of episode note",23"Code": "34133-9"24},25"Type": "Summarization of episode note",26"DateTime": "2020-12-10T17:09:50.000Z",27"Title": "C-CDA R2.1 Patient Record: Adolfo Kessler",28"Locale": "US"29},30"Patient": {31"Demographics": {32"MaritalStatus": "",33"Religion": "",34"Ethnicity": "Not hispanic or latino",35"Race": "White",36"Address": {37"County": "",38"ZIP": "53711",39"Country": "",40"State": "Wisconsin",41"City": "Madison",42"StreetAddress": "602 Schiller Junction Suite 68"43},44"Sex": "Male",45"SSN": "",46"DOB": "2002-10-31T17:09:50.000Z",47"EmailAddresses": [],48"PhoneNumber": {49"Mobile": "",50"Office": "",51"Home": ""52},53"LastName": "Kessler",54"FirstName": "Adolfo"55},56"Identifiers": [57{58"IDType": "2.16.840.1.113883.19.5",59"ID": "j8p2NtTbAL7rTWRRhe7kSK"60}61]62}63}
Choose this option if you want to receive a full list of documents related to the patient. 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.
For this option, use the DocumentQuery and DocumentGet event types of ClinicalSummary; if you’re using FHIR®, use the DocumentReference resource. The response returns PDFs or any other documents that are attached to the patient record.
- Using Postman or curl, send the ClinicalSummary.DocumentQuery request with the relevant metadata:
- Patient ID and ID Type: These values are returned in the PatientSearch response.
- Organization OID: The organization OID is equivalent to the HCID value (from the DocumentQuery response) and should go in the Meta.FacilityCode field of your request.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.
Data model example: Search for a document listbash1curl \2-X POST https://api.redoxengine.com/endpoint \3-H "Content-Type: application/json" \4-H "Authorization: Bearer $API_TOKEN" \5-d '{6"Meta": {7"Extensions": {8"sender-organization-id": {9"url": "https://api.redoxengine.com/extensions/sender-organization-id",10// The OID represents the organization sending the query. You can use a top-level OID, but if there are multiple levels, it helps to be specific.11"string": "{{organization_oid}}"12},13"user-id": {14"url": "https://api.redoxengine.com/extensions/user-id",15// The user ID should be human-readable (typically name, not an ID) and change per query based on the initiating user.16"string": "{{user-name}}"17},18"user-role": {19"url": "https://api.redoxengine.com/extensions/user-role",20// Defines the role of the user identified above. This must be a SNOMED CT code.21"coding": {22"code": "{{user_role}}",23// This is set for the default code (112247003), but change this if you have a different code.24"display": "Medical Doctor"25}26},27"purpose-of-use": {28"url": "https://api.redoxengine.com/extensions/purpose-of-use",29// Identifies the purpose of the Carequality query, which is almost always TREATMENT. If another purpose of use, other Carequality participants likely won't respond.30"coding": {31"code": "TREATMENT",32"display": "Treatment"33}34}35},36"DataModel": "Clinical Summary",37"EventType": "DocumentQuery",38# Remove in production39"Test": true,40"Destinations": [41{42// This is a standard Redox value that varies between environments. Refer to the destination IDs "Search for patient records" article.43"ID": "{{destination-id-for-environment}}"44}45],46// Enter the OID of the organization you want to search.47// We use Redox for the example below.48// For a broad search, this should be the Organization OID-type ID from the location response.49// For a narrow search, this should be the organization OID from the organization response.50"FacilityCode": "2.16.840.1.113883.3.6147.458.2"51},52"Patient": {53"Identifiers": [54{55// Similar to "FacilityCode" this should come from the location response or from the patient search for a narrow search.56"ID": "{{PatientID}}",57"IDType": "{{PatientIDType}}"58}59]60}61}API referenceReview the ClinicalSummary data model schema for more technical details.
FHIR example: Search for a document listbash1curl --location --request POST 'https://testapi.redoxengine.com/fhir/R4/ceq-xca:2.16.840.1.113883.3.6147.458.2/Development/DocumentReference/_search' \2--header 'Authorization: Bearer $API_TOKEN' \3--header 'x-sender-organization-id: {{your_oid}}' \4--header 'x-user-id: {{user_human_readable_id}}' \5--header 'x-user-role: {{user_role}}' \6--header 'x-purpose-of-use: TREATMENT' \7--header 'redox-source-id: {{your_source_id_if_multiple}}' \8--header 'Content-Type: application/x-www-form-urlencoded' \9--data-urlencode 'patient=681d2103-f883-4334-886b-59358580dcb1^2.16.840.1.113883.3.6147.458.2'FHIR API referenceReview the FHIR® DocumentReference resource for more technical details.
- 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.Data model example: Successful response for a document listjson1{2"Documents": [3{4"Author": {5"Location": {6"Type": "General Medicine",7"Department": "Health Encounter Site",8"Facility": "Cool.io"9},10"Type": "",11"Credentials": [],12"FirstName": null,13"LastName": null,14"IDType": null,15"ID": null16},17"Location": {18"Department": "Health Encounter Site"19},20"Visit": {21"Type": "Summarization of episode note",22"EndDateTime": "2020-12-10T17:09:50.000Z",23"StartDateTime": "2020-12-10T17:09:50.000Z"24},25"Type": {26"Name": "Summarization of episode note",27"Codeset": "2.16.840.1.113883.6.1",28"Code": "34133-9"29},30"FileType": "text/xml",31"HCID": "urn:oid:2.16.840.1.113883.3.6147.458.8080.2.2.1",32"RepositoryUniqueId": "2.16.840.1.113883.3.6147.458.8080.2.2.1",33"DateTime": null,34"Locale": "en-US",35"Title": "Summarization of episode note",36"ID": "Mi4xNi44NDAuMS4xMTM4ODMuMTkuNV45MmNjZTU0YS0zYTlmLTYzNGEtNGQyMC03ZTU2NmVjYzMyYWI=^Mi4xNi44NDAuMS4xMTM4ODMuMy42MTQ3LjQ1OC44MDgwLjIuMi4x^dXJuOm9pZDoyLjE2Ljg0MC4xLjExMzg4My4zLjYxNDcuNDU4LjgwODAuMi4yLjE="37}38],39"Patient": {40"Identifiers": [41{42"ID": "45e5fadd-0496-4e48-be26-a06d78f8e950",43"IDType": "2.16.840.1.113883.3.6147.458.2"44}45]46},47"Meta": {48"DataModel": "Clinical Summary",49"EventType": "DocumentQuery",50"Message": {51"ID": 1272034688952},53"Source": {54"ID": "d9c19117-7778-47fd-9f55-b3bccc4055f8"55},56"Destinations": [57{58"ID": "ec745338-8849-43ad-a7ce-4bc5bf1d8b89",59"Name": "Carequality Sandbox - XCA"60}61],62"Logs": [63{64"ID": "f30fbf24-5e3f-4503-b899-1fc247f0f996",65"AttemptID": "2a215fde-a385-4f5a-bfb1-28a14e7a9605"66}67]68}69}FHIR example: Successful response for a document listjson1{2"body": {3"resourceType": "Bundle",4"type": "searchset",5"total": 2,6"entry": [7{8"resource": {9"resourceType": "DocumentReference",10"id": "NzVjYjRhZDQtZTVmOS00Y2QzLTg3NTAtZWI1MDUwNTIxZTBk^Mi4xNi44NDAuMS4xMTM4ODMuMy42MTQ3LjQ1OC41NTUxLjIuMi4x^dXJuOm9pZDoyLjE2Ljg0MC4xLjExMzg4My4zLjYxNDcuNDU4LjU1NTEuMi4yLjE=",11"masterIdentifier": {12"system": "urn:uuid:2e82c1f6-a085-4c72-9da3-8640a32e42ab",13"value": "75cb4ad4-e5f9-4cd3-8750-eb5050521e0d"14},15"status": "current",16"category": {17"coding": [18{19"system": "2.16.840.1.113883.6.1",20"code": "18842-5"21}22],23"text": "Progress Note"24},25"subject": {26"type": "Patient",27"identifier": [28{29"system": "2.16.840.1.113883.3.6147.458.2",30"value": "681d2103-f883-4334-886b-59358580dcb1"31}32]33},34"description": "Progress Note",35"content": [36{37"attachment": {38"contentType": "text/xml",39"language": "en-US",40"title": "Progress Note"41},42"format": "urn:ihe:iti:xds:2017:mimeTypeSufficient"43}44],45"context": {46"encounter": [47{48"status": "planned",49"facilityType": {50"text": "General Medicine"51},52"practiceSetting": {53"text": "General Medicine"54}55}56]57}58},59"search": {60"mode": "match"61},62"fullUrl": "urn:uuid:7635b589-3335-4280-98fb-335194cb5d4a"63},64{65"resource": {66"resourceType": "DocumentReference",67"id": "dXJuOnJlZG94OkNhcmVxdWFsaXR5VGVzdC01NTUxLVNhbmRib3gtUHJvZHVjdGlvbjptZWRpYV5iMTY5MjY3Yy0xMGM5LTRmZTMtOTFhZS05Y2tmNTcwM2U5MGw=^Mi4xNi44NDAuMS4xMTM4ODMuMy42MTQ3LjQ1OC41NTUxLjIuMi4x^dXJuOm9pZDoyLjE2Ljg0MC4xLjExMzg4My4zLjYxNDcuNDU4LjU1NTEuMi4yLjE=",68"masterIdentifier": {69"system": "urn:uuid:2e82c1f6-a085-4c72-9da3-8640a32e42ab",70"value": "urn:redox:CarequalityTest-5551-Sandbox-Production:media^b169267c-10c9-4fe3-91ae-9ckf5703e90l"71},72"status": "current",73"category": {74"coding": [75{76"system": "2.16.840.1.113883.6.1",77"code": "34133-9"78}79],80"text": "Empty File"81},82"subject": {83"type": "Patient",84"identifier": [85{86"system": "2.16.840.1.113883.3.6147.458.2",87"value": "681d2103-f883-4334-886b-59358580dcb1"88}89]90},91"description": "Empty File",92"content": [93{94"attachment": {95"contentType": "application/pdf",96"language": "en-US",97"title": "Empty File"98},99"format": "urn:ihe:iti:xds:2017:mimeTypeSufficient"100}101],102"context": {103"encounter": [104{105"status": "planned",106"facilityType": {107"text": "General Medicine"108},109"practiceSetting": {110"text": "General Medicine"111}112}113]114}115},116"search": {117"mode": "match"118},119"fullUrl": "urn:uuid:ce97b6ec-c42b-4048-87b7-d659fceaf75c"120}121]122}123}
- 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.
Data model example: Retrieve a documentbash1curl \2-X POST https://api.redoxengine.com/endpoint \3-H "Content-Type: application/json" \4-H "Authorization: Bearer $API_TOKEN" \5-d '{6"Meta": {7"Extensions": {8"sender-organization-id": {9"url": "https://api.redoxengine.com/extensions/sender-organization-id",10// This is the OID that represents you as an organization. If you have multiple levels, it helps to be specific, but you can also use your top-level.11"string": "{{organization_oid}}"12},13"user-id": {14"url": "https://api.redoxengine.com/extensions/user-id",15// This should change per request and should be a human-readable ID for the user (typically name, not an actual ID).16"string": "{{user_human_readable_id}}"17},18"user-role": {19"url": "https://api.redoxengine.com/extensions/user-role",20// This is a SNOMED CT code that relates to the user above. See https://www.hl7.org/fhir/valueset-practitioner-role.html.21"coding": {22"code": "{{user_role}}",23// This is set for the default code (112247003), but this should change if you have a different code.24"display": "Medical Doctor"25}26},27"purpose-of-use": {28"url": "https://api.redoxengine.com/extensions/purpose-of-use",29// Identifies the purpose of the query, which is almost always TREATMENT. If another purpose of use, other Carequality participants likely won't respond.30"coding": {31"code": "TREATMENT",32"display": "Treatment"33}34}35},36"DataModel": "Clinical Summary",37"EventType": "DocumentGet",38"EventDateTime": "2019-08-02T20:09:22.089Z",39"Test": true,40"Destinations": [41{42// This is a standard Redox value that varies between environments. Refer to the destination IDs in the "Search for patient records" article.43"ID": "{{destination-id-for-environment}}"44}45],46// Enter the OID of the Carequality organization you want to search. We use Redox in the example below.47// For a broad search, use the Organization OID-type ID from the location response.48// For a narrow search, use the organization OID from the organization response.49"FacilityCode": "2.16.840.1.113883.3.6147.458.2"50},51"Document": {52// Use the value from the previous document query response.53"ID": "{{document-id}}"54}55}FHIR example: Retrieve a documentbash1curl --location --request GET 'https://testapi.redoxengine.com/fhir/R4/ceq-xca:2.16.840.1.113883.3.6147.458.2/Development/DocumentReference/NzVjYjRhZDQtZTVmOS00Y2QzLTg3NTAtZWI1MDUwNTIxZTBk^Mi4xNi44NDAuMS4xMTM4ODMuMy42MTQ3LjQ1OC41NTUxLjIuMi4x^dXJuOm9pZDoyLjE2Ljg0MC4xLjExMzg4My4zLjYxNDcuNDU4LjU1NTEuMi4yLjE=' \2--header 'Authorization: Bearer $API_TOKEN' \3--header 'x-sender-organization-id: {{your_oid}}' \4--header 'x-user-id: {{user_human_readable_id}}' \5--header 'x-user-role: {{user_role}}' \6--header 'x-purpose-of-use: TREATMENT' \7--header 'redox-source-id: {{your_source_id_if_multiple}}' - If the request is successful, you receive a synchronous ClinicalSummary.DocumentGetResponse with the relevant document of interest.What format to expect
For Redox data models
The response includes the raw content in the Data field and the type of content in FileType.
- For CDA content, FileType is always text/xml, and Data is UTF-8 text content. In this case, we translate the JSON to match the ClinicalSummary.VisitQueryResponse data model (see the response format).
- For non-CDA content, FileType is whatever Carequality sends, and Data is always base64-encoded content. This is to support file types like application/pdf or XML content that isn’t CDA.
For FHIR®
The content will always be base64-encoded and parsing isn’t performed.
Data model example (abbreviated): Successful document retrievaljson1"Meta": {2"DataModel": "Clinical Summary",3"EventType": "DocumentGet",4"Message": {5"ID": 127203469366},7"Source": {8"ID": "d9c19117-7778-47fd-9f55-b3bccc4055f8"9},10"Destinations": [11{12"ID": "ec745338-8849-43ad-a7ce-4bc5bf1d8b89",13"Name": "Carequality Sandbox - XCA"14}15],16"Logs": [17{18"ID": "8ebf45b3-3c60-4d35-8f93-a1b754eded73",19"AttemptID": "62dc89d4-6d59-418b-95b1-131fae7a721d"20}21]22},23"Header": {24"Document": {25"Title": "C-CDA R2.1 Patient Record: Adolfo Kessler",26"Visit": {27"Location": null,28"VisitNumber": "",29"EndDateTime": "",30"StartDateTime": ""31},32"Author": {33"Location": {34"Facility": "MADISON ANESTHESIOLOGY CONSULTANTS, LLP"35}36},37"ID": "2.16.840.1.113883.19.5^92cce54a-3a9f-634a-4d20-7e566ecc32ab",38"TypeCode": {39"AltCodes": [],40"CodeSystemName": "LOINC",41"CodeSystem": "2.16.840.1.113883.6.1",42"Name": "Summarization of episode note",43"Code": "34133-9"44},45"Type": "Summarization of episode note",46"DateTime": "2020-12-10T17:09:50.000Z",47"Locale": "US"48},49"Patient": {50"Demographics": {51"MaritalStatus": "",52"Religion": "",53"Ethnicity": "Not hispanic or latino",54"Race": "White",55"Address": {56"County": "",57"ZIP": "53711",58"Country": "",59"State": "Wisconsin",60"City": "Madison",61"StreetAddress": "602 Schiller Junction Suite 68"62},63"Sex": "Male",64"SSN": "",65"DOB": "2002-10-31T17:09:50.000Z",66"EmailAddresses": [],67"PhoneNumber": {68"Mobile": "",69"Office": "",70"Home": ""71},72"LastName": "Kessler",73"FirstName": "Adolfo"74},75"Identifiers": [76{77"IDType": "2.16.840.1.113883.19.5",78"ID": "j8p2NtTbAL7rTWRRhe7kSK"79}80]81}82},83"Data": "",84"FileType": "text/xml",85...86}FHIR example: Successful document retrievaljson1{2"body": {3"content": [4{5"attachment": {6"contentType": "text/xml",7"data": "PD94bWwgdmVyc2lv...base64 content omitted for brevity"8}9}10],11"status": "current",12"masterIdentifier": {13"value": "2.16.840.1.113883.3.6147.458.5551.2.2.1^75cb4ad4-e5f9-4cd3-8750-eb5050521e0d",14"system": "urn:oid:2.16.840.1.113883.3.6147.458.5551.2.2.1"15},16"resourceType": "DocumentReference"17}18}
Basic information
- Carequality test patients (contains patient data for you to use when testing)
How-to
Troubleshooting
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®.