Search for patient records

To search for patient records, you first need to identify organizations that have seen your patient. Then you can request any documents for that patient from each of those organizations.

If you want to know where you can get patient records from, explore a list of active Carequality participants with this search tool.

You can also check out the Carequality test patient data for context on the code examples we provide.

You have two options for finding and obtaining a patient’s record: 

1. Search for a patient using the Redox Record Locator Service: If you don’t know where the patient is located or if the patient may exists in multiple locations, you can ask Redox to provide a list of possibilities. This is the the most common option since it allows you to identify all of the organizations where a patient’s record may exist.
2. Search for a patient with your own location search: If you have a static list of locations you wish to search or know exactly which organizations have records for the patient, you can search those specific organizations or locations directly. Keep in mind that this means you can only search one organization at a time.

Regardless of the patient search option you use, each query contains required metadata fields that identify the requesting user and their organization, specify the purpose of use, and direct the request to the target organization. These fields exist within the Meta section of the query.

You can see how the Meta fields are populated in this example:

{
  "Meta": {
    "DataModel": "PatientSearch",
    "EventType": "Query",
    "Destinations": [
      {
        "ID": "1ca254a8-8d42-4593-abb4-b21399d9de57"
      }
    ],
    // This field is used to list the organization to be queried
    "FacilityCode": "{{OID of facility to be queried}}",
    "Extensions": {
      // This extension is used to identify the querying organization's OID
      "sender-organization-id": {
        "string": "{{Your OID here}}.{{facility number}}"
      },
      // This extension is used to identify the querying organization name, generally the name of your covered entity.
      "organization-name": {
        "string": "Beverly Hills Telehealth"
      },
      // This extension should include the name of the querying user
      "user-id": {
        "string": "Doolittle, John"
      },
      // This extension should include the role of the querying user.
      // You may use SNOMED, but any codeset can be used.
      "user-role": {
        "coding": {
          "code": "112247003",
          "display": "Medical Doctor"
        }
      },
      // The purpose of use for your query, generaly Treatment
      "purpose-of-use": {
        "coding": {
          "code": "TREATMENT"
        }
      }
    }
  }
}

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

This popular option relies on Redox Record Locator Service to do the heavy lifting for you. Record locator service looks for your patient's record at Carequality participant facilities within the same areas as your organization and the patient's home address (if supplied). Record locator service also leverages results from other Redox client searches so we can go beyond the search area, if possible. 

1. If you already have the network patient ID, you can skip to step 3. If you don't have the network patient ID, using Postman or curl, send a PatientSearch.Query request with the patient's demographics to the Redox gateway (2.16.840.1.113883.3.6147.458.2).

   Example: Search for a patient

   bash

   Copy
2. Record locator services takes the patient's demographics and returns the network patient ID.
3. Using Postman or curl, send a PatientSearch.LocationQuery request with the network patient ID to the record locator destination (adf917b5-1496-4241-87e2-ed20434b1fdb for staging requests; 97f2dc1d-c71b-43a7-a436-9b789d44c804 for production requests).

   Example: Search for locations

   bash

   Copy
4. The response returns a list of locations where the patient exists—along with the patient’s localized IDs at each location, which we validate.

   Example: Successful response for location search

   json

   Copy

The Meta.Extensions.task-status.string field contains a status of either Active or Success.

The response waits up to 10 seconds to reach a Success state. If unable to reach Success in that time, the response retains an Active status. You can retry the exact request repeatedly until it reaches a Success state.

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. If you already have an organization and its respective OID to search, you can skip to step 4. If you don’t have an OID for the organization you want to search, send the Organization.Query request. With this query, you search by ZIP code radius or organization name.

   Example: Search for organizations

   bash

   Copy
2. If the request is successful, you receive a synchronous Organization.QueryResponse with the relevant organization results.

   Example: Successful response for organization search

   json

   Copy
3. From the results list, you can select one or all of these organizations to then run a patient search.
4. Now that you have an organization to search, 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 each request.

   Where to find the OID

   The OID is found in the FacilityCode field of the Organization.QueryResponse that you received in the previous step.

   Data model example: Search for a patient within one organization

   bash

   Copy
5. If your search matches a patient at the given organization, the response returns the patient’s identifier and additional details.

   Example: Successful response for a patient search within one organization

   json

   Copy

   If a patient isn’t found, the response returns an empty array.
6. Repeat steps 4 and 5 for every organization you want to search.

• Request patient documents