# Search for patient records with FHIR > **Who can use this how-to** > > - Existing customers using **Network Onramps** to connect to the **Carequality Interoperability Framework**. > - Existing customers with a direct connection to the **Carequality Interoperability Framework** (i.e., without Redox). To search for patient records, you first need to identify organizations that have seen your patient. Then you can [request patient documents](/how-to-use-redox/interact-with-clinical-networks/onramp-to-carequality/request-patient-documents-with-fhir) from those organizations. If you want to know where you can get patient records from, [explore a list of active Carequality participants](https://carequality.org/active-sites-search/). You can also [check out test patient data ](/how-to-use-redox/interact-with-clinical-networks/onramp-to-carequality/test-sandbox-for-onramp-to-Carequality)for context on the code examples we provide or for your own testing. > **Data model option** > > Did you know you can also do this workflow with Redox data models? [Learn how to search for patient records with the Redox Data Model API](/how-to-use-redox/interact-with-clinical-networks/onramp-to-carequality/search-for-patient-records). ## Steps for patient search with FHIR With FHIR, you can perform a narrow patient search, meaning you can search a specific organization for patient records. Follow the steps below to search for a patient. If you already know the organization OID you want to search, skip to step 2: 1. **Find relevant organizations to search**. First, you need to find where the patient’s records may exist. You can use parameters like ZIP code or radius around the patient’s address to find a list of organizations. The response returns a list of matching organization(s) with their OID(s). 2. **Search for patient records with OID(s)**. Skip directly to this step if you already have a static list of OID(s) to search. Otherwise, use the results from the previous step. Keep in mind you can only search one organization per query. > **Redox patient ID for FHIR** > > For every patient, your system assigns a local patient ID, which may or may not be unique. > > Redox also assigns a unique network patient ID for the same patient, which is used to identify the patient within Carequality. > > As a result, the patient ID in the data on demand repository isn’t the same as the patient ID in Carequality. To find the network ID for a patient, send a `Patient_search` with the patient demographics to the Redox gateway: `2.16.840.1.113883.3.6147.458.2`. > **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 the comments from the code examples (starting with `//`). > - Replace any variables (e.g., `{{variable here}}`). > - Add the `Redox-source-id` header if you have multiple sources. We don’t include this header 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 our troubleshooting tips](/troubleshooting/troubleshoot-oauth-api-key-errors) if you run into errors. ## Query components ### FHIR headers for queries Each query contains required metadata headers that identify the requesting user and their organization, specify the purpose of use, and direct the request to the target organization. This table contains the HTTP headers for the relevant metadata when using the Redox FHIR API to search for patients. | Header | Description | Notes | | --------------- | ---------- | ------------- | | `x-sender-organization-id` | The OID of your Carequality organization. This specifies that your organization is sending the query. | It helps to be specific if you have multiple levels within your Carequality organization. However, you can also use your organization’s top-level OID. | | `x-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. This isn’t necessary for patient searches with record locator service. | | `x-user-role` | The role of the user sending the request. | You must use a SNOMED value for this field. [Check out the U.S. Health Information knowledge base](https://ushik.ahrq.gov/ViewItemDetails?system=si&itemKey=86829000) for a list of available SNOMED values. | | `x-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. If you have a different purpose of use, other Carequality participants aren't likely to respond. Remember that to be a Carequality participant, you must also push data. | ### FHIR search parameters | **Parameter** | **Description** | **Example** | | --- | --- | --- | | `_id` | The organization OID of a Carequality participant. | `2.16.840.1.113883.3.6147.458.2` | | `name` | The organization name of a Carequality participant. These aren’t unique values, and you’re not able to search aliases. | `redox` | | `name-searchtype` | Used in conjunction with `name` and designates whether the name search should be `contains` or `exact`. This is non-normative but results in one of the search values as defined in FHIR. [Review the HL7 FHIR spec](https://www.hl7.org/fhir/search.html#modifiercontains). | `contains` | | `address-city` | Used in conjunction with `name-searchtype` to perform an exact search for a city. | `Madison` | | `address-state` | Used in conjunction with `name-searchtype` to perform an exact search for a U.S. state. | `WI` | | `address-postalcode` | Used in conjunction with `name-searchtype` to perform an exact search for a ZIP code. | `53703` | | `radius` | Should be used in conjunction with any of the `address-*` search parameters. | `50` | | `active` | The type of patient records to include in the response. By default, this is set to `true`, which means only active patient records should be returned. If `false`, deleted records may be included. | `false` | | `index` | Where to start searching if paging through patient records. | `0` | | `limit` | The number of patient records to return in the response payload. | `100` | ### Destination slugs You must populate any test queries with the appropriate FHIR destination slug for the specific type of request: | Query purpose | Destination slug | | --------------- | ---------- | | Query for/create/update/delete an organization | `ceq-orgs` | | Perform a patient search within a specific organization | `ceq-xcpd:{{OID-FROM-ORGANIZATION-QUERY}}` | | Search for a clinical summary/document | `ceq-xca:{{OID-FROM-ORGANIZATION-QUERY}}` | > **Which OID to use** > > The `{{OID-FROM-ORGANIZATION-QUERY}}` is the OID of the Carequality participant you’re querying, not the OID of your Carequality organization. ## Step 1: Find organizations to search Follow these steps to find organization OIDs of Carequality participants you want to query for patient records. You can skip this section if you already have the organization OIDs you need. 1. Send the `Organization_search` query to search by ZIP code radius or organization name. We recommend including the FHIR headers we defined above, but it’s not required. **FHIR example: Search for organizations** ```bash curl --request POST \ --url https://api.redoxengine.com/fhir/R4/ceq-orgs/{{ENVIRONMENT}}/Organization/_search \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'x-purpose-of-use: TREATMENT' \ --header 'x-sender-organization-id: {{YOUR-ORGANIZATION-OID}}' \ --header 'x-user-id: {{SENDING-USER-NAME}}' \ --header 'x-user-role: {{SNOMED-USER-ROLE}}' \ --data _id=2.16.840.1.113883.3.6147.458.2 ``` > **API reference** > > [Review the `Organization` schema ](https://docs.redoxengine.com/permalink/9387fce6-d4b4-52be-adb2-70f56f73bdf5-search-type)for more technical details. 2. If the request is successful, you receive a synchronous response with the relevant organization results. **FHIR Example: Successful response for organization search** ```json { "resourceType": "Bundle", "type": "searchset", "link": [ { "relation": "self", "url": "https://stage-dir-ceq.sequoiaproject.org/fhir-stu3/1.0.1/Organization?_format=xml" } ], "total": 1, "entry": [ { "resource": { "resourceType": "Organization", "id": "a05b27f0-f6d3-013d-188b-06d6044a85ae", "text": { "status": "generated", "div": "
Redox Gateway
" }, "meta": { "versionId": "1", "lastUpdated": "2024-03-01T16:21:07Z" }, "identifier": [ { "use": "official", "system": "http://www.hl7.org/oid/", "value": "2.16.840.1.113883.3.6147.458.2" } ], "active": true, "type": [ { "coding": [ { "system": "http://hl7.org/fhir/organization-type", "code": "Connection" } ] } ], "name": "Redox Gateway", "alias": [ "" ], "address": [ { "use": "work", "type": "both", "line": [ "25 West Main Street, Suite 500" ], "city": "Madison", "state": "WI", "postalCode": "53703", "country": "USA" } ], "partOf": { "identifier": { "use": "official", "system": "http://www.hl7.org/oid/", "type": { "text": "HCID" }, "value": "2.16.840.1.113883.3.6147.458" } }, "contact": [ { "purpose": { "text": "Technical" }, "name": { "use": "official", "text": "Redox, Carequality" }, "telecom": [ { "system": "email", "value": "carequality@redoxengine.com", "use": "work" }, { "system": "phone", "value": "+16085359501", "use": "work" } ] }, { "purpose": { "text": "Business" }, "name": { "use": "official", "text": "Redox, Carequality" }, "telecom": [ { "system": "email", "value": "support@redoxengine.com", "use": "work" }, { "system": "phone", "value": "+16085359501", "use": "work" } ] } ] }, "fullUrl": "https://stage-dir-ceq.sequoiaproject.org/fhir-stu3/1.0.1/Organization/2.16.840.1.113883.3.6147.458.2", "search": { "mode": "match" } } ] } ``` 3. Select one or more organizations from the results list to search. ## Step 2: Search for patients with organization OIDs If you know exactly where a patient was seen previously, you can search for a patient at an individual organization. If you want to search multiple organizations, you must search them one at a time. 1. Send the `PatientSearch.Query` request with the patient’s demographics to see if that organization has your patient’s records. You must use the organization’s OID in the URL of each request. > **Where to find the OID** > > The OID is found in the `identifier.value` field of the `Organization` response you received in the previous step. **FHIR example: Search for a patient within one organization** ```bash curl --request POST \ --url https://api.redoxengine.com/fhir/R4/ceq-xcpd:2.16.840.1.113883.3.6147.458.2/{{ENVIRONMENT}}/Patient/_search \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'x-purpose-of-use: TREATMENT' \ --header 'x-sender-organization-id: {{YOUR-ORGANIZATION-OID}}' \ --header 'x-user-id: {{SENDING-USER-NAME}}' \ --header 'x-user-role: {{SNOMED-USER-ROLE}}' \ --data 'identifier=http://hl7.org/fhir/sid/us-ssn|010-10-1000' \ --data birthdate=19980601 \ --data family=Bixby \ --data given=Pauline ``` > **FHIR API reference** > > [Review the `Patient` schema](https://docs.redoxengine.com/permalink/760c1cad-07a0-5a62-98a2-42b2a25c0534-search-type) for more technical details. 2. If your search matches a patient at the given organization, the response returns the patient’s identifier and additional details. If a patient isn’t found, the response returns an empty array. **FHIR example: Successful response for a patient search within one organization** ```json { "resourceType": "Bundle", "type": "searchset", "total": 1, "entry": [ { "resource": { "resourceType": "Patient", "id": "681d2103-f883-4334-886b-59358580dcb1^2.16.840.1.113883.3.6147.458.2", "identifier": [ { "value": "681d2103-f883-4334-886b-59358580dcb1", "system": "urn:oid:2.16.840.1.113883.3.6147.458.2" } ], "name": [ { "given": [ "pauline" ], "family": "bixby" } ], "gender": "female", "birthDate": "1998-06-01", "telecom": [ { "value": "18088675309", "system": "phone", "use": "home" } ], "address": [ { "line": [ "4762 walnut street" ], "city": "mt. horeb", "state": "WI", "postalCode": "53572" } ] }, "search": { "mode": "match" }, "fullUrl": "urn:uuid:93fbe6ac-5136-438d-98b2-55ef3d75ef1d" } ] } ``` 3. Repeat these steps for every organization you want to search. ## Next steps - [Request patient documents with FHIR](/how-to-use-redox/interact-with-clinical-networks/onramp-to-carequality/request-patient-documents-with-fhir) > **Resources for onramp to Carequality with FHIR ** > > **Basic information** > > - [Interact with clinical networks](/how-to-use-redox/interact-with-clinical-networks) > - [Carequality identity and organization structure](/how-to-use-redox/interact-with-clinical-networks/onramp-to-carequality/carequality-identity-and-organization-structure) > - [Carequality FAQ](/how-to-use-redox/interact-with-clinical-networks/onramp-to-carequality/carequality-interoperability-framework-faq) > - [Carequality test patients](/how-to-use-redox/interact-with-clinical-networks/onramp-to-carequality/test-sandbox-for-onramp-to-Carequality) (contains patient data to use when testing) > > **How-to** > > - [Set up your onramp to Carequality](/how-to-use-redox/interact-with-clinical-networks/onramp-to-carequality/set-up-your-onramp-to-carequality) > - [Create an organization record with FHIR](/how-to-use-redox/interact-with-clinical-networks/onramp-to-carequality/create-an-organization-record-with-fhir) > - [Search for patient records with FHIR](/how-to-use-redox/interact-with-clinical-networks/onramp-to-carequality/search-for-patient-records-with-fhir) > - [Request patient documents with FHIR](/how-to-use-redox/interact-with-clinical-networks/onramp-to-carequality/request-patient-documents-with-fhir) > - [Maintain your Redox repository](/how-to-use-redox/interact-with-clinical-networks/onramp-to-carequality/maintain-your-redox-repository-for-carequality) > > **Troubleshooting** > > - [Common Carequality errors](/troubleshooting/troubleshoot-carequality-interoperability-framework-errors)