# Search TEFCA-CommonWell for patient records

> **Who can use this how-to**
>
> - Existing customers using Network Onramps to connect to TEFCA via CommonWell

## Prerequisites

- You must have populated your Redox data on demand repository with your existing patients. [Learn how to populate your patient repository](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/populate-your-patient-repository-for-tefca-commonwell).
- (_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:


<details>
<summary>TEFCA-CommonWell terms to know</summary>

| **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. |

</details>




<details>
<summary>Metadata for TEFCA-CommonWell requests</summary>

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. |

</details>




<details>
<summary>Destination IDs for TEFCA-CommonWell</summary>

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. |

## 

</details>



## Search for patient records in TEFCA-CommonWell

Searching TEFCA-CommonWell for patient records is an optional step if you want to:

- Confirm that you’ve already added a patient record in your repository for TEFCA-CommonWell. If the patient isn’t found with the steps in this how-to guide, you should add it. [Learn how to populate your patient repository](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/populate-your-patient-repository-for-tefca-commonwell). 
- Locate specific sites to directly query. After locating a site, use the organization OID in the location query response to [request patient records](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/request-patient-documents-from-tefca-commonwell). 

First, using Postman or `curl`, send a `PatientSearch.LocationQuery` request with either the network patient ID or patient demographics to the CommonWell EMPI destination.

- The `Meta.Destination.ID` changes based on environment type:
  - <u>**Development destination ID**</u>: `adf917b5-1496-4241-87e2-ed20434b1fdb`
  - <u>**Production destination ID**</u>: `97f2dc1d-c71b-43a7-a436-9b789d44c804`
- For production queries, set the `Test` value to `false`.
- The network patient ID is the patient identifier from TEFCA-CommonWell. If you don’t have it, you can leave the `Identifiers` array empty and rely on demographic matching. 
- For patient demographics, [review the `LocationQuery` schema](https://docs.redoxengine.com/permalink/patient-search-location-query) for full requirements. 

> **What demographic information to include**
>
> Include as much demographic information as possible when searching for a patient. Most TEFCA-CommonWell participants use advanced matching algorithms that require additional data elements beyond the minimum.
>
> At a minimum, include these in your search:
>
> - given name
> - family name
> - birthdate
> - gender
>
> However, you shouldn’t expect results if you only use the minimum data points. You should also include what you have of these:
>
> - Social Security number (SSN)
> - ZIP code

**Example: Search for locations 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": "PatientSearch",
        "EventType": "LocationQuery",
        "Test": true,
        "Destinations": [
            {
                "ID": "adf917b5-1496-4241-87e2-ed20434b1fdb"
            }
        ]
    },
    "Patient": {
        "Identifiers": [],
   "Demographics": {
      "FirstName": "Redox",
      "MiddleName": null,
      "LastName": "Tester",
      "DOB": "1910-01-01",
      "SSN": "101-01-0001",
      "Sex": "Male",
      "Race": "White",
      "IsHispanic": null,
      "Religion": null,
      "MaritalStatus": "Single",
      "IsDeceased": null,
      "DeathDateTime": null,
      "Language": "en",
      "Citizenship": [],
      "Address": {
        "ZIP": "56789",
      }
    }
    }
}'
```

The response returns identifiers, including both `ID` and `IDType` (i.e., PIAA) and demographic information about the patient, including `Organization.Identifiers[].ID`. [Review the `LocationQueryResponse` schema](https://docs.redoxengine.com/permalink/patient-search-location-query-response) for full context and technical details.

> **CommonWell EMPI results**
>
> With CommonWell EMPI, results are only returned for matches that already exist within your own organization’s repository. In other words, demographics results from _external_ repositories won’t be returned unless a demographics match already exists within your CommonWell dataset. 
>
> To get matches, make sure to register patients of interest in your system before querying in order to get data back. Registration can happen through a `PatientAdmin` feed or backfill to transfer patients from one clinical network to another. [Learn more about populating your repository](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/populate-your-patient-repository-for-tefca-commonwell).
>
> If you’re not getting matches, it’s possible that data exists in the network but you haven’t registered the patient yet in your system.

**Example: Successful response for location search in TEFCA-CommonWell**

```json
{
  "Patients": [
    {
      "Identifiers": [
        {
          "ID": "sandbox-tester-123",
          "IDType": "2.16.840.1.113883.3.6147.450.0.2.19301.0.1"
        }
      ],
      "Demographics": {
        "FirstName": "Redox",
        "LastName": "Tester",
        "Sex": "Male",
        "DOB": "1910-01-01",
        "Address": {
          "StreetAddress": "123 Pasture Lane",
          "City": "Madison",
          "State": "WI",
          "ZIP": "56789"
        },
        "PhoneNumber": {
          "Home": "+18088675309"
        }
      },
      "Organization": {
        "Name": "St. Barnabas Hospital",
        "Identifiers": [
          {
            "ID": "2.16.840.1.113883.3.6147.450.0.2.19301.0.1"
          }
        ]
      }
    },
    {
      "Identifiers": [
        {
          "ID": "sandbox-tester-on-sandbox-system-456",
          "IDType": "2.16.840.1.113883.3.6147.450.0.2.19260.0.2"
        }
      ],
      "Demographics": {
        "FirstName": "Redox",
        "LastName": "Tester",
        "Sex": "Male",
        "DOB": "1910-01-01",
        "Address": {
          "StreetAddress": "123 Pasture Lane",
          "City": "Madison",
          "State": "WI",
          "ZIP": "56789"
        },
        "PhoneNumber": {
          "Home": "+18088675309"
        }
      },
      "Organization": {
        "Name": "redox",
        "Identifiers": [
          {
            "ID": "2.16.840.1.113883.3.6147.450.0.2.19260.0.1"
          }
        ]
      }
    }
  ],
  "Meta": {
    "DataModel": "PatientSearch",
    "EventType": "LocationQuery",
    "Source": {
      "ID": "6b8c8f4e-7a69-4575-acb7-58efc8593302",
      "Name": "Integration-CW EETS"
    },
    "Destinations": [
      {
        "ID": "3122bfff-f1fb-4fdf-97de-294f24338229",
        "Name": "CommonWell EMPI [Integration]"
      }
    ],
    "Logs": [
      {
        "ID": "0196f332-ae3c-7ce3-be23-fe2faa35cf7f",
        "AttemptID": "0196f332-ae3c-77fd-aadd-484c95063472"
      }
    ]
  }
}
```

## Next steps

- [Request patient documents](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/request-patient-documents-from-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)