# Request patient documents from TEFCA-CommonWell > **Who can use this how-to** > > - Existing customers using Network Onramps to connect to TEFCA via CommonWell To request documents from TEFCA-CommonWell, you use a two-step workflow: 1. Request a list of relevant document IDs. 2. Retrieve a specific document from the list. You cannot retrieve a document without first knowing its ID from step 1. ## Prerequisites - You must have [created a TEFCA-CommonWell organization record](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/create-a-tefca-commonwell-organization-record) and [populated your Redox data on demand repository with your existing patients](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/populate-your-patient-repository-for-tefca-commonwell). - You must use the patient ID and ID type from your own system (i.e., the MR or internal patient ID) to request documents. _Don't use the PIAA OID or other TEFCA-CommonWell assigned identifiers_, since those are used for matching only, not for document retrieval_._ - (_Optional_) Test sending these requests with our TEFCA-CommonWell sandbox. [Learn about our TEFCA-CommonWell sandbox](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/test-sandbox-for-onramp-to-tefca-commonwell). > **Use curl for technical validation** > > You can copy our code examples and send the test requests with `curl` ([learn more about curl](https://curl.haxx.se/docs/manpage.html)) instead of Postman. If you do, remember to: > > - Remove any comments from the code examples (starting with `//`). > - Replace any variables (e.g., `{{YOUR-VARIABLE}}`). > - 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](/basics/data-exchange-with-redox/Managing-source-details-in-outgoing-requests). > - 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](/troubleshooting/troubleshoot-tefca-commonwell-errors) > - [Troubleshoot OAuth API key errors](/troubleshooting/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 requests This table contains the metadata fields for Redox data models if you’re querying or sending requests to 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. To generate your organization OID for the `sender-organization-id` extension, [refer to TEFCA identity and organization structure](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/tefca-identity-and-organization-structure). | | `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](https://www.hl7.org/fhir/valueset-practitioner-role.html). | | `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 (`PatientSearch.LocationQuery`) | `3122bfff-f1fb-4fdf-97de-294f24338229` | `7fd005ac-d788-40c5-b4e8-b57bb8e310a9` | | Create or update an organization (`Organization.New`, `Organization.Update`) | `3122bfff-f1fb-4fdf-97de-294f24338229` | `7fd005ac-d788-40c5-b4e8-b57bb8e310a9` | | Search for a clinical summary/document (`ClinicalSummary.DocumentQuery`, `ClinicalSummary.DocumentGet`) | `cf1dca0e-98de-432b-8c9a-dd039816df0e` | `79981c00-b9c4-40a9-9844-01980e6e524e` | | Save patient details to your repository (`PatientAdmin.NewPatient`, `PatientAdmin.PatientUpdate`, `PatientAdmin.PatientMerge`) | `3122bfff-f1fb-4fdf-97de-294f24338229` | `7fd005ac-d788-40c5-b4e8-b57bb8e310a9` | | Save documents to your repository (`ClinicalSummary.VisitQuery`, `ClinicalSummary.VisitPush`) | This is specific to your organization. Redox provides the correct ID. | This is specific to your organization. Redox provides the correct ID. | ##
## Step 1: Request a list of document IDs Send `ClinicalSummary.DocumentQuery` to query TEFCA-CommonWell for a list of document IDs related to a specific patient. - The `Meta.Destination.ID` changes based on environment type: - **Development destination ID**: `cf1dca0e-98de-432b-8c9a-dd039816df0e` - **Production destination ID**: `79981c00-b9c4-40a9-9844-01980e6e524e` - For production queries, set the `Test` value to `false`. - For `Patient.Identifiers.ID` and `Patient.Identifiers.IDType`, use the patient values within your own organization, or use the ones in [the response from a patient search](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/search-tefca-commonwell-for-patient-records). - Enter one of the following options for the `Meta.FacilityCode` depending on the result you want (we use Redox for the example below): - **Option 1: Broach search**. To return a list of document IDs from all external organizations where the patient is known, either enter your own OID or set it to `null`. This initiates a fan-out query to the clinical network. > **When using your own OID** > > 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: Narrow search**. To return a list of document IDs from one site, enter the specific OID. This comes in [the response from a patient search](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/search-tefca-commonwell-for-patient-records). - [Review the Clinical Summary data model](https://docs.redoxengine.com/permalink/clinical-summary) schema for full requirements. > **Which documents to request** > > 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 curl \ -X POST https://api.redoxengine.com/endpoint \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $API_TOKEN" \ -d '{ "Meta": { "Extensions": { "sender-organization-id": { "url": "https://api.redoxengine.com/extensions/sender-organization-id", "string": "{{ORGANIZATION-OID}}" }, "user-id": { "url": "https://api.redoxengine.com/extensions/user-id", "string": "{{SENDING-USER-NAME}}" }, "user-role": { "url": "https://api.redoxengine.com/extensions/user-role", "coding": { "code": "112247003", "display": "Medical Doctor" } }, "purpose-of-use": { "url": "https://api.redoxengine.com/extensions/purpose-of-use", "coding": { "code": "TREATMENT", "display": "Treatment" } } }, "DataModel": "Clinical Summary", "EventType": "DocumentQuery", "Test": true, "Destinations": [ { "ID": "cf1dca0e-98de-432b-8c9a-dd039816df0e" } ], "FacilityCode": "2.16.840.1.113883.3.6147.458.2" }, "Patient": { "Identifiers": [ { "ID": "{{PATIENT-ID-FROM-LOCATION-SEARCH}}", "IDType": "{{PATIENT-ID-TYPE-FROM-LOCATION-SEARCH}}" } ] } } ``` If successful, you receive `ClinicalSummary.DocumentQueryResponse` with a list of document IDs related to the patient record. The included document metadata helps you 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. The returned document IDs correspond to patient IDs and ID types 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 { "Patient": { "Identifiers": [ { "ID": "sandbox-tester-on-sandbox-system-456", "IDType": "2.16.840.1.113883.3.6147.450.0.2.19260.0.2" }, { "ID": "101-01-0001", "IDType": "SSN" } ] }, "Documents": [ { "ID": "056a016c-1acf-48cb-a331-40e4ee2aade8", "Visit": { "ID": "30311442", "StartDateTime": "2025-05-02T19:36:34.787Z", "EndDateTime": "2025-05-02T19:36:34.787Z" }, "DateTime": "2025-05-08T20:10:11.570Z", "FileType": "text/xml", "Location": { "Department": "Vista Oaks Clinic", "Type": "Outpatient Clinic", "Facility": "RHS Vista Oaks Clinic" } } ], "Meta": { "DataModel": "Clinical Summary", "EventType": "DocumentQuery", "Message": { "ID": 69912737500 }, "Source": { "ID": "4c2216a9-cf64-4c14-b817-9cdb2e855bad", "Name": "CommonWell Incoming" }, "Destinations": [ { "ID": "5aa140d8-79e5-46c5-870f-d0369a344b01", "Name": "CommonWell Sandbox [Integration]" } ], "Logs": [ { "ID": "0196ef6d-addc-76d9-8d16-fb9a6fd60c2c", "AttemptID": "0196ef6d-addc-7c5a-bc4e-d38774471a6c" } ] } } ``` ## Step 2: Retrieve a specific document from the list Send `ClinicalSummary.DocumentGet` to query for any document from the list. Enter the relevant metadata: - The `Meta.Destination.ID` changes based on environment type: - **Development destination ID**: `cf1dca0e-98de-432b-8c9a-dd039816df0e` - **Production destination ID**: `79981c00-b9c4-40a9-9844-01980e6e524e` - For production queries, set the `Test` value to `false`. - For the `Meta.FacilityCode`, use the value from the previous step’s response. We use Redox in the example below. - For `Document.ID`, enter the value from the previous step’s response. > **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 curl \ -X POST https://api.redoxengine.com/endpoint \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $API_TOKEN" \ -d '{ "Meta": { "Extensions": { "sender-organization-id": { "url": "https://api.redoxengine.com/extensions/sender-organization-id", "string": "{{ORGANIZATION-OID}}" }, "user-id": { "url": "https://api.redoxengine.com/extensions/user-id", "string": "{{SENDING-USER-NAME}}" }, "user-role": { "url": "https://api.redoxengine.com/extensions/user-role", "coding": { "code": "112247003", "display": "Medical Doctor" } }, "purpose-of-use": { "url": "https://api.redoxengine.com/extensions/purpose-of-use", "coding": { "code": "TREATMENT", "display": "Treatment" } } }, "DataModel": "Clinical Summary", "EventType": "DocumentGet", "EventDateTime": "2019-08-02T20:09:22.089Z", "Test": true, "Destinations": [ { "ID": "cf1dca0e-98de-432b-8c9a-dd039816df0e" } ], "FacilityCode": "2.16.840.1.113883.3.6147.458.2" }, "Document": { "ID": "{{DOCUMENT-ID-FROM-PREVIOUS-RESPONSE}}" } } ``` If successful, you receive `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`. > > - If the returned document follows a C-CDA format, you receive it in a Redox-parsed view matching the `ClinicalSummary.VisitQueryResponse` data model ([see the response format](https://docs.redoxengine.com/permalink/clinical-summary-visit-query-response)). [Check out required C-CDA elements](https://docs.redoxengine.com/permalink/1ldmpAmaxAriJ7Ei0zYn3Q/#what-data-is-exchanged). The `FileType` is always `text`/`xml`, and `Data` is `UTF-8` text content. > - 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. The `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. > > 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. **Example (abbreviated): Successful document retrieval from TEFCA-CommonWell** ```json "Meta": { "DataModel": "Clinical Summary", "EventType": "DocumentGet", "Message": { "ID": 12720346936 }, "Source": { "ID": "4c2216a9-cf64-4c14-b817-9cdb2e855bad", "Name": "CommonWell Incoming" }, "Destinations": [ { "ID": "5aa140d8-79e5-46c5-870f-d0369a344b01", "Name": "CommonWell Sandbox [Integration]" } ], "Logs": [ { "ID": "0196ef7b-696c-71a2-a4bc-91730fd33ab0", "AttemptID": "0196ef7b-696c-7b82-81d8-cdba601ecc50" } ] }, "Header": { "Document": { "Title": "C-CDA R2.1 Patient Record: Adolfo Kessler", "Visit": { "Location": null, "VisitNumber": "", "EndDateTime": "", "StartDateTime": "" }, "Author": { "Location": { "Facility": "MADISON ANESTHESIOLOGY CONSULTANTS, LLP" } }, "ID": "2.16.840.1.113883.19.5^92cce54a-3a9f-634a-4d20-7e566ecc32ab", "TypeCode": { "AltCodes": [], "CodeSystemName": "LOINC", "CodeSystem": "2.16.840.1.113883.6.1", "Name": "Summarization of episode note", "Code": "34133-9" }, "Type": "Summarization of episode note", "DateTime": "2020-12-10T17:09:50.000Z", "Locale": "US" }, "Patient": { "Demographics": { "MaritalStatus": "", "Religion": "", "Ethnicity": "Not hispanic or latino", "Race": "White", "Address": { "County": "", "ZIP": "53711", "Country": "", "State": "Wisconsin", "City": "Madison", "StreetAddress": "602 Schiller Junction Suite 68" }, "Sex": "Male", "SSN": "", "DOB": "2002-10-31T17:09:50.000Z", "EmailAddresses": [], "PhoneNumber": { "Mobile": "", "Office": "", "Home": "" }, "LastName": "Kessler", "FirstName": "Adolfo" }, "Identifiers": [ { "IDType": "2.16.840.1.113883.19.5", "ID": "j8p2NtTbAL7rTWRRhe7kSK" } ] } }, "Data": "{{UTF-8 text content}}", "FileType": "text/xml", ... } ``` ## Next steps - [Maintain your Redox repository](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/maintain-your-redox-repository-for-tefca-commonwell) > **Onramp to TEFCA resources** > > **Basic information** > > - [Interact with clinical networks](/how-to-use-redox/interact-with-clinical-networks) > - [TEFCA identity and organization structure](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/tefca-identity-and-organization-structure) > > **How-to** > > - [Set up your onramp to TEFCA-CommonWell](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/set-up-your-onramp-to-tefca-commonwell) > - [Test sandbox for onramp to TEFCA-CommonWell](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/test-sandbox-for-onramp-to-tefca-commonwell) > - [Populate your patient repository for TEFCA-CommonWell](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/populate-your-patient-repository-for-tefca-commonwell) > - [Create a TEFCA-CommonWell organization record](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/create-a-tefca-commonwell-organization-record) > - [Search TEFCA-CommonWell for patient records](/how-to-use-redox/interact-with-clinical-networks/onramp-to-carequality/search-for-patient-records) > - [Request patient documents from TEFCA-CommonWell](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/request-patient-documents-from-tefca-commonwell) > - [Maintain your Redox repository](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/maintain-your-redox-repository-for-tefca-commonwell) > > **Troubleshooting** > > - [Common TEFCA errors](/troubleshooting/troubleshoot-tefca-commonwell-errors)