# Populate your patient repository for TEFCA-CommonWell > **Who can use this how-to** > > - Existing customers using Network Onramps Before querying TEFCA-CommonWell for data, you must load your existing patient data into your Redox **data on demand repository**. [Learn more about data on demand](/basics/data-exchange-with-redox/data-on-demand). After first populating your patient repository, you must keep your patient demographics and records up-to-date as you continue patient care. ## Prerequisites - You must have qualified for TEFCA and set up your credentials and OIDs. [Learn more about setting up your onramp to TEFCA](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/set-up-your-onramp-to-tefca-commonwell). - You must have created your TEFCA-Commonwell organization record. [Learn more about creating an organization record](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/create-a-tefca-commonwell-organization-record). - Be familiar with the following terms and concepts to send requests 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. | ##
## Notes about code examples The extensions in the code examples are all required for any `PatientAdmin` messages. [Learn more about extensions](/api-reference/redox-data-model-api/extensions-for-data-models). > **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) ## Step 1: Populate your repostiory with existing patients This is a critical first step in your TEFCA-CommonWell workflow. It must be done before querying TEFCA-CommonWell or maintaining your patient records. Send a `PatientAdmin.NewPatient` request for each of your patients to create their patient record in TEFCA-CommonWell to associate your patient with the same patient in external organizations. You must use at least one patient identifier with the ID Type of the patient OID assigned to you. - The `Meta.Destination.ID` changes based on environment type: - **Development destination ID**: `3122bfff-f1fb-4fdf-97de-294f24338229` - **Production destination ID**: 7fd005ac-d788-40c5-b4e8-b57bb8e310a9 - For production queries, set the `Test` value to `false`. - The patient identifier and demographics below are example values only. Replace them with the relevant patient information. - The patient identifier should be the MRN or primary ID of the patient in your system. - The ID type should map to the value Redox provides. Typically, this means mapping a value like `MR` to this OID. This OID is linked to the repository and required to associate the patient. - For demographics, [review the PatientAdmin data model](https://docs.redoxengine.com/permalink/patient-admin-new-patient) schema for full requirements. **Example: Create a new patient in 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": "PatientAdmin", "EventType": "NewPatient", "Test": true, "Destinations": [ { "ID": "3122bfff-f1fb-4fdf-97de-294f24338229" } ] }, "Patient": { "Identifiers": [ { "ID": "1234", "IDType": "MR" } ], "Demographics": { "FirstName": "Timothy", "MiddleName": "Paul", "LastName": "Bixby", "DOB": "2008-01-06", "SSN": "101-01-0001", "Sex": "Male", "Race": "White", "IsHispanic": null, "MaritalStatus": "Married", "IsDeceased": null, "DeathDateTime": null, "PhoneNumber": { "Home": "+18088675301", "Office": null, "Mobile": null }, "EmailAddresses": [], "Language": "en", "Citizenship": [], "Address": { "StreetAddress": "4762 Hickory Street", "City": "Monroe", "State": "WI", "ZIP": "53566", "County": "Green", "Country": "US" } }, "Notes": [], "Contacts": [ { "FirstName": "Barbara", "MiddleName": null, "LastName": "Bixby", "Address": { "StreetAddress": "4762 Hickory Street", "City": "Monroe", "State": "WI", "ZIP": "53566", "County": "Green", "Country": "US" }, "PhoneNumber": { "Home": "+18088675303", "Office": "+17077543758", "Mobile": "+19189368865" }, "RelationToPatient": "Mother", "EmailAddresses": [ "barb.bixby@test.net" ], "Roles": [ "Emergency Contact" ] } ], "Allergies": [ { "Code": "7982", "Codeset": "RxNorm", "Name": "Penicillin", "Type": { "Code": null, "Codeset": null, "Name": null }, "OnsetDateTime": null, "Reaction": [ { "Code": "28926001", "Codeset": "SNOMED CT", "Name": "Rash" }, { "Code": "247472004", "Codeset": "SNOMED CT", "Name": "Hives" } ], "Severity": { "Code": null, "Codeset": null, "Name": null }, "Status": null } ], "PCP": { "NPI": "4356789876", "ID": "4356789876", "IDType": "NPI", "FirstName": "Pat", "LastName": "Granite", "Credentials": [ "MD" ], "Address": { "StreetAddress": "123 Main St.", "City": "Madison", "State": "WI", "ZIP": "53703", "County": "Dane", "Country": "USA" }, "EmailAddresses": [], "PhoneNumber": { "Office": "+16085551234" }, "Location": { "Type": null, "Facility": null, "Department": null, "Room": null } }, "Guarantor": { "Number": "10001910", "FirstName": "Kent", "MiddleName": null, "LastName": "Bixby", "SSN": null, "DOB": null, "Sex": null, "Spouse": { "FirstName": "Barbara", "LastName": "Bixby" }, "Address": { "StreetAddress": "4762 Hickory Street", "City": "Monroe", "State": "WI", "ZIP": "53566", "County": "Green", "Country": "USA" }, "PhoneNumber": { "Home": null, "Business": null, "Mobile": null }, "EmailAddresses": [], "Type": null, "RelationToPatient": "Father", "Employer": { "Name": "Accelerator Labs", "Address": { "StreetAddress": "1456 Old Sauk Road", "City": "Madison", "State": "WI", "ZIP": "53719", "County": "Dane", "Country": "USA" }, "PhoneNumber": "+18083451121" } }, "Insurances": [ { "Plan": { "ID": "31572", "IDType": "Payor ID", "Name": "HMO Deductible Plan", "Type": null }, "MemberNumber": null, "Company": { "ID": "60054", "IDType": null, "Name": "aetna (60054 0131)", "Address": { "StreetAddress": "PO Box 14080", "City": "Lexington", "State": "KY", "ZIP": "40512-4079", "County": "Fayette", "Country": "US" }, "PhoneNumber": "+18089541123" }, "GroupNumber": "847025-024-0009", "GroupName": "Accelerator Labs", "EffectiveDate": "2015-01-01", "ExpirationDate": "2020-12-31", "PolicyNumber": "9140860055", "AgreementType": null, "CoverageType": null, "Insured": { "Identifiers": [], "LastName": null, "MiddleName": null, "FirstName": null, "SSN": null, "Relationship": null, "DOB": null, "Sex": null, "Address": { "StreetAddress": null, "City": null, "State": null, "ZIP": null, "County": null, "Country": null } } } ] } } ``` Repeat this step every time you add a new patient to your patient care. ## Step 2: Update existing patient demographics Complete this step every time demographics or contact information changes for existing patients. Send a `PatientAdmin.PatientUpdate` request with the updated details. Patient demographics must be updated before you can query for their data again. - The destination ID changes based on environment type: - **Development destination ID**: `3122bfff-f1fb-4fdf-97de-294f24338229` - **Production destination ID**: 7fd005ac-d788-40c5-b4e8-b57bb8e310a9 - For production queries, set the `Test` value to `false`. - The patient identifier and demographics below are example values only. Replace them with the relevant patient information. - The patient identifier should be the MRN or primary ID of the patient in your system. - The ID type should map to the value Redox provides. Typically, this means mapping a value like `MR` to this OID. This OID is linked to the repository and required to associate the patient. - For demographics, [review the PatientAdmin data model](https://docs.redoxengine.com/permalink/patient-admin-patient-update) schema for full requirements. **Example: Update an existing patient in 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": "PatientAdmin", "EventType": "PatientUpdate", "Test": true, "Destinations": [ { "ID": "3122bfff-f1fb-4fdf-97de-294f24338229" } ] }, "Patient": { "Identifiers": [ { "ID": "1234", "IDType": "MR" } ], "Demographics": { "FirstName": "Timothy", "MiddleName": "Paul", "LastName": "Bixby", "DOB": "2008-01-06", "SSN": "101-01-0001", "Sex": "Male", "Race": "White", "IsHispanic": null, "MaritalStatus": "Married", "IsDeceased": null, "DeathDateTime": null, "PhoneNumber": { "Home": "+18088675301", "Office": null, "Mobile": null }, "EmailAddresses": [], "Language": "en", "Citizenship": [], "Address": { "StreetAddress": "4435 Victoria Ln", "City": "Madison", "State": "WI", "ZIP": "53719", "County": "Dane", "Country": "US" } }, "Notes": [], "Contacts": [ { "FirstName": "Barbara", "MiddleName": null, "LastName": "Bixby", "Address": { "StreetAddress": "4762 Hickory Street", "City": "Monroe", "State": "WI", "ZIP": "53566", "County": "Green", "Country": "US" }, "PhoneNumber": { "Home": "+18088675303", "Office": "+17077543758", "Mobile": "+19189368865" }, "RelationToPatient": "Mother", "EmailAddresses": [ "barb.bixby@test.net" ], "Roles": [ "Emergency Contact" ] } ], "Diagnoses": [ { "Code": "R07.0", "Codeset": "ICD-10", "Name": "Pain in throat", "Type": null, "DocumentedDateTime": null } ], "Allergies": [ { "Code": "7982", "Codeset": "RxNorm", "Name": "Penicillin", "Type": { "Code": null, "Codeset": null, "Name": null }, "OnsetDateTime": null, "Reaction": [ { "Code": "28926001", "Codeset": "SNOMED CT", "Name": "Rash" }, { "Code": "247472004", "Codeset": "SNOMED CT", "Name": "Hives" } ], "Severity": { "Code": null, "Codeset": null, "Name": null }, "Status": null } ], "PCP": { "NPI": "4356789876", "ID": "4356789876", "IDType": "NPI", "FirstName": "Pat", "LastName": "Granite", "Credentials": [ "MD" ], "Address": { "StreetAddress": "123 Main St.", "City": "Madison", "State": "WI", "ZIP": "53703", "County": "Dane", "Country": "USA" }, "EmailAddresses": [], "PhoneNumber": { "Office": "+16085551234" }, "Location": { "Type": null, "Facility": null, "Department": null, "Room": null } }, "Insurances": [ { "Plan": { "ID": "31572", "IDType": "Payor ID", "Name": "HMO Deductible Plan", "Type": null }, "MemberNumber": null, "Company": { "ID": "60054", "IDType": null, "Name": "aetna (60054 0131)", "Address": { "StreetAddress": "PO Box 14080", "City": "Lexington", "State": "KY", "ZIP": "40512-4079", "County": "Fayette", "Country": "US" }, "PhoneNumber": "+18089541123" }, "GroupNumber": "847025-024-0009", "GroupName": "Accelerator Labs", "EffectiveDate": "2015-01-01", "ExpirationDate": "2020-12-31", "PolicyNumber": "9140860055", "AgreementType": null, "CoverageType": null, "Insured": { "Identifiers": [], "LastName": null, "MiddleName": null, "FirstName": null, "SSN": null, "Relationship": null, "DOB": null, "Sex": null, "Address": { "StreetAddress": null, "City": null, "State": null, "ZIP": null, "County": null, "Country": null } } } ], "Guarantor": { "Number": "10001910", "FirstName": "Kent", "MiddleName": null, "LastName": "Bixby", "SSN": null, "DOB": null, "Sex": null, "Spouse": { "FirstName": "Barbara", "LastName": "Bixby" }, "Address": { "StreetAddress": "4762 Hickory Street", "City": "Monroe", "State": "WI", "ZIP": "53566", "County": "Green", "Country": "USA" }, "PhoneNumber": { "Home": null, "Business": null, "Mobile": null }, "EmailAddresses": [], "Type": null, "RelationToPatient": "Father", "Employer": { "Name": "Accelerator Labs", "Address": { "StreetAddress": "1456 Old Sauk Road", "City": "Madison", "State": "WI", "ZIP": "53719", "County": "Dane", "Country": "USA" }, "PhoneNumber": "+18083451121" } } } } ``` ## Step 3: Combine duplicate patient records Complete this step every time you identify duplicate records for the same patient. Send a `PatientAdmin.PatientMerge` request to merge the patient records and replace the previous identifiers with the new one. Patient records must be merged appropriately before you can query for their data again. - The destination ID changes based on environment type: - **Development destination ID**: `3122bfff-f1fb-4fdf-97de-294f24338229` - **Production destination ID**: 7fd005ac-d788-40c5-b4e8-b57bb8e310a9 - For production queries, set the `Test` value to `false`. - The patient identifier and demographics below are example values only. Replace them with the relevant patient information. - The patient identifier should be the MRN or primary ID of the patient in your system. - The ID type should map to the value Redox provides. Typically, this means mapping a value like `MR` to this OID. This OID is linked to the repository and required to associate the patient. - For demographics, [review the PatientAdmin data model](https://docs.redoxengine.com/permalink/patient-admin-patient-merge) schema for full requirements. **Example: Merge patient records in 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", // The role of the user identified above. This must be a SNOMED CT code. "coding": { "code": "112247003", "display": "Medical Doctor" } }, "purpose-of-use": { "url": "https://api.redoxengine.com/extensions/purpose-of-use", "coding": { "code": "TREATMENT", "display": "Treatment" } } }, "DataModel": "PatientAdmin", "EventType": "PatientMerge", "Test": true, "Destinations": [ { "ID": "3122bfff-f1fb-4fdf-97de-294f24338229" } ] }, "Patient": { "Identifiers": [ { "ID": "{{NEW-PATIENT-ID}}", "IDType": "MR" } ], "PreviousIdentifiers": [ { "ID": "{{OLD-PATIENT-ID}}", "IDType": "MR" } ], "Demographics": { "FirstName": "Timothy", "MiddleName": "Paul", "LastName": "Bixby", "DOB": "2008-01-06", "SSN": "101-01-0001", "Sex": "Male", "Race": "White", "IsHispanic": null, "MaritalStatus": "Married", "IsDeceased": null, "DeathDateTime": null, "PhoneNumber": { "Home": "+18088675301", "Office": null, "Mobile": null }, "EmailAddresses": [], "Language": "en", "Citizenship": [], "Address": { "StreetAddress": "4762 Hickory Street", "City": "Monroe", "State": "WI", "ZIP": "53566", "County": "Green", "Country": "US" } }, "Notes": [] } } ``` ## Next steps - [Search for patient records](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/search-tefca-commonwell-for-patient-records) > **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)