Request patient documents from TEFCA-CommonWell

• You must have already ingested your patient records into TEFCA-CommonWell so that your patient IDs can be located.
• You must use your own patient ID and ID type to request documents. Don't use the TEFCA-CommonWell global ID.
• (Optional) Test sending these requests with our TEFCA-CommonWell sandbox. Learn about our TEFCA-CommonWell sandbox.

  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:

  • Troubleshoot TEFCA-CommonWell errors
  • Troubleshoot OAuth API key errors

• Be familiar with the following terms and concepts to send your queries to TEFCA-CommonWell:

  TEFCA-CommonWell terms to know

  Term	Description
  Organization or object ID (OID)	Identifies a particular healthcare organization within the TEFCA-CommonWell network. When you create a new organization record within TEFCA, the returned OID becomes the sender organization ID for your later queries.
  Patient Identity Assigning Authority (PIAA)	The entity that assigns patient identifiers in the healthcare system. This value becomes the ID type in the metadata of TEFCA-CommonWell queries for documents.

  Metadata for TEFCA-CommonWell queries

  This table contains the metadata fields for Redox data models if you’re querying TEFCA-CommonWell via the Redox Data Model API.

  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. Check out the destination ID table for specifics.	For patient searches, this is a CommonWell EMPI destination. For document searches, this is a CommonWell XCA destination. For responding with information about your patients, this is your own document repository.
  Meta.FacilityCode	Set to your organization OID or null.	This is required for document searches. A less common workflow might include directly querying to an external organization within the network. In that case, use their organization OID.
  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’re providing services for.
  Meta.Extensions.sender-organization-id	The organizational OID to identify your organization as the one sending the request.	This field is used for audit purposes and for search logic.
  Meta.Extensions.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.
  Meta.Extensions.user-role	The role of the user sending the request.	You must use a SNOMED value for this field. See SNOMED codes.
  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 Network Onramps.

  Destination IDs for TEFCA-CommonWell

  You must populate any test requests with the appropriate destination ID in the Meta.Destinations array based on the environment and type of requests:

  Query purpose	Development ID	Production ID
  Perform a patient search	3122bfff-f1fb-4fdf-97de-294f24338229	7fd005ac-d788-40c5-b4e8-b57bb8e310a9
  Query for/create/update/delete an organization	3122bfff-f1fb-4fdf-97de-294f24338229	7fd005ac-d788-40c5-b4e8-b57bb8e310a9
  Search for a clinical summary/document	cf1dca0e-98de-432b-8c9a-dd039816df0e	79981c00-b9c4-40a9-9844-01980e6e524e
  Save patient details to your repository	3122bfff-f1fb-4fdf-97de-294f24338229	7fd005ac-d788-40c5-b4e8-b57bb8e310a9
  Save documents to your repository	This is specific to your organization. Redox provides the correct ID.	This is specific to your organization. Redox provides the correct ID.

Use ClinicalSummary.DocumentQuery to query TEFCA-CommonWell for a list of document IDs related to a specific patient. The response returns a list of document IDs related to the patient record.

1. Using Postman or curl, send ClinicalSummary.DocumentQuery with the relevant metadata:
   • Patient ID and ID type: Use the patient ID and ID type within your own organization.
   • Organization OID: The organization OID should go in the Meta.FacilityCode field of your request.
     • Option 1: For the FacilityCode, enter your own OID or set it to null. This results in a fan-out query which returns a list of document IDs from all external organizations where the patient is known in the clinical network.
       • You never get documents from your own organization if you use your own OID, since TEFCA-CommonWell assumes you already have your own patient documents.
     • Option 2: For the FacilityCode, enter the OID of a specific site you want to query. You can get a specific site's OID by searching for patient records and using the OID from the query results. This results a list of document IDs from one specific site.

       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.

       Example: Search for a document list from TEFCA-CommonWell

       bash

       Copy

       1
       curl \
       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. Use the OID that corresponds to your CommonWell configuration.
       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 TEFCA query, which is almost always TREATMENT. 
       30
                       "coding": {
       31
                           "code": "TREATMENT",
       32
                           "display": "Treatment"
       33
                       }
       34
                   }
       35
               },
       36
               "DataModel": "Clinical Summary",
       37
               "EventType": "DocumentQuery",
       38
               # Remove in production
       39
               "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
               // This should be the organization OID from the organization response in the LocationQueryResponse.
       49
               "FacilityCode": "2.16.840.1.113883.3.6147.458.2"
       50
           },
       51
           "Patient": {
       52
               "Identifiers": [
       53
                   {
       54
                       // Similar to "FacilityCode" this should come from the LocationQueryResponse search.
       55
                       "ID": "{{PatientID}}",
       56
                       "IDType": "{{PatientIDType}}"
       57
                   }
       58
               ]
       59
           }
       60
       }

       API reference

       Review the ClinicalSummary data model schema for more technical details.

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.

   Results from external organizations

   The results in the DocumentQueryResponse are from external organizations, not your own data on demand repository. So the returned document IDs and ID types correspond to patient IDs and ID types that are from external organizations. This means they won’t necessarily match your own patient ID type from the query.

   In other words, CommonWell assumes that you’re querying any external organization for your own patients. You might see a list of results from different organizations, not necessarily including the organization(s) listed in the LocationQueryResponse.

   Example: Successful response for a document list from TEFCA-CommonWell

   json

   Copy

   1
   {
   2
     "Patient": {
   3
       "Identifiers": [
   4
         {
   5
           "ID": "sandbox-tester-on-sandbox-system-456",
   6
           "IDType": "2.16.840.1.113883.3.6147.450.0.2.19260.0.2"
   7
         },
   8
         {
   9
           "ID": "101-01-0001",
   10
           "IDType": "SSN"
   11
         }
   12
       ]
   13
     },
   14
     "Documents": [
   15
       {
   16
         "ID": "056a016c-1acf-48cb-a331-40e4ee2aade8",
   17
         "Visit": {
   18
           "ID": "30311442",
   19
           "StartDateTime": "2025-05-02T19:36:34.787Z",
   20
           "EndDateTime": "2025-05-02T19:36:34.787Z"
   21
         },
   22
         "DateTime": "2025-05-08T20:10:11.570Z",
   23
         "FileType": "text/xml",
   24
         "Location": {
   25
           "Department": "Vista Oaks Clinic",
   26
           "Type": "Outpatient Clinic",
   27
           "Facility": "RHS Vista Oaks Clinic"
   28
         }
   29
       }
   30
     ],
   31
     "Meta": {
   32
       "DataModel": "Clinical Summary",
   33
       "EventType": "DocumentQuery",
   34
       "Message": {
   35
         "ID": 69912737500
   36
       },
   37
       "Source": {
   38
         "ID": "4c2216a9-cf64-4c14-b817-9cdb2e855bad",
   39
         "Name": "CommonWell Incoming"
   40
       },
   41
       "Destinations": [
   42
         {
   43
           "ID": "5aa140d8-79e5-46c5-870f-d0369a344b01",
   44
           "Name": "CommonWell Sandbox [Integration]"
   45
         }
   46
       ],
   47
       "Logs": [
   48
         {
   49
           "ID": "0196ef6d-addc-76d9-8d16-fb9a6fd60c2c",
   50
           "AttemptID": "0196ef6d-addc-7c5a-bc4e-d38774471a6c"
   51
         }
   52
       ]
   53
     }
   54
   }

Use ClinicalSummary.DocumentGet to query for any document from the list.

• If the returned document follows a C-CDA format, you receive it in a Redox-parsed view for any data that we can parse. Check out required C-CDA elements.
• If the returned document is a PDF or any other format, you receive it in raw XML, which can be useful if you have your own document renderer.

1. Using Postman or curl, send ClinicalSummary.DocumentGet 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 at a time. We recommend retrieving only the most relevant documents, not every document on the list.

   Example: Retrieve a document from TEFCA-CommonWell

   bash

   Copy

   1
   curl \
   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, 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
           // Use the Organization OID-type ID from the location response.
   48
           "FacilityCode": "2.16.840.1.113883.3.6147.458.2"
   49
       },
   50
       "Document": {
   51
           // Use the value from the previous document query response.
   52
           "ID": "{{document-id}}"
   53
       }
   54
   }
2. If the request is successful, you receive a synchronous ClinicalSummary.DocumentGetResponse with the relevant document of interest.

   What format to expect

   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 the clinical network sends, and Data is always base64-encoded content. This is to support file types like application/pdf or XML content that isn’t CDA.

   Example (abbreviated): Successful document retrieval from TEFCA-CommonWell

   json

   Copy

   1
   "Meta": {
   2
           "DataModel": "Clinical Summary",
   3
           "EventType": "DocumentGet",
   4
           "Message": {
   5
               "ID": 12720346936
   6
           },
   7
      "Source": {
   8
         "ID": "4c2216a9-cf64-4c14-b817-9cdb2e855bad",
   9
         "Name": "CommonWell Incoming"
   10
       },
   11
       "Destinations": [
   12
         {
   13
           "ID": "5aa140d8-79e5-46c5-870f-d0369a344b01",
   14
           "Name": "CommonWell Sandbox [Integration]"
   15
         }
   16
       ],
   17
       "Logs": [
   18
         {
   19
           "ID": "0196ef7b-696c-71a2-a4bc-91730fd33ab0",
   20
           "AttemptID": "0196ef7b-696c-7b82-81d8-cdba601ecc50"
   21
         }
   22
       ]
   23
       },
   24
         "Header": {
   25
           "Document": {
   26
               "Title": "C-CDA R2.1 Patient Record: Adolfo Kessler",
   27
               "Visit": {
   28
                   "Location": null,
   29
                   "VisitNumber": "",
   30
                   "EndDateTime": "",
   31
                   "StartDateTime": ""
   32
               },
   33
               "Author": {
   34
                   "Location": {
   35
                       "Facility": "MADISON ANESTHESIOLOGY CONSULTANTS, LLP"
   36
                   }
   37
               },
   38
               "ID": "2.16.840.1.113883.19.5^92cce54a-3a9f-634a-4d20-7e566ecc32ab",
   39
               "TypeCode": {
   40
                   "AltCodes": [],
   41
                   "CodeSystemName": "LOINC",
   42
                   "CodeSystem": "2.16.840.1.113883.6.1",
   43
                   "Name": "Summarization of episode note",
   44
                   "Code": "34133-9"
   45
               },
   46
               "Type": "Summarization of episode note",
   47
               "DateTime": "2020-12-10T17:09:50.000Z",
   48
               "Locale": "US"
   49
           },
   50
           "Patient": {
   51
               "Demographics": {
   52
                   "MaritalStatus": "",
   53
                   "Religion": "",
   54
                   "Ethnicity": "Not hispanic or latino",
   55
                   "Race": "White",
   56
                   "Address": {
   57
                       "County": "",
   58
                       "ZIP": "53711",
   59
                       "Country": "",
   60
                       "State": "Wisconsin",
   61
                       "City": "Madison",
   62
                       "StreetAddress": "602 Schiller Junction Suite 68"
   63
                   },
   64
                   "Sex": "Male",
   65
                   "SSN": "",
   66
                   "DOB": "2002-10-31T17:09:50.000Z",
   67
                   "EmailAddresses": [],
   68
                   "PhoneNumber": {
   69
                       "Mobile": "",
   70
                       "Office": "",
   71
                       "Home": ""
   72
                   },
   73
                   "LastName": "Kessler",
   74
                   "FirstName": "Adolfo"
   75
               },
   76
               "Identifiers": [
   77
                   {
   78
                       "IDType": "2.16.840.1.113883.19.5",
   79
                       "ID": "j8p2NtTbAL7rTWRRhe7kSK"
   80
                   }
   81
               ]
   82
           }
   83
       },
   84
     "Data": "",
   85
     "FileType": "text/xml",
   86
     ...
   87
   }

• Maintain your Redox repository