Search for patient records with FHIR

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

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

You can also check out test patient data for context on the code examples we provide or for your own testing.

With FHIR®, you can perform a narrow patient search, meaning you can search a specific organization for patient records.

There are two steps for this. However, you can skip step #1 if you already have the organization OID(s):

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 step #1. Keep in mind you can only search one organization per query.

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.

You must populate any test queries with the appropriate FHIR® destination slug for the specific type of request:

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

   Copy

   1
   curl --request POST \
   2
     --url https://api.redoxengine.com/fhir/R4/ceq-orgs/Development/Organization/_search \
   3
     --header 'Content-Type: application/x-www-form-urlencoded' \
   4
     --header 'x-purpose-of-use: TREATMENT' \
   5
     --header 'x-sender-organization-id: {{your_oid}}' \
   6
     --header 'x-user-id: {{user_human_readable_id}}' \
   7
     --header 'x-user-role: {{user_role}}' \
   8
     --data _id=2.16.840.1.113883.3.6147.458.2

   API reference

   Review the Organization schema 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

   Copy

   1
   {
   2
     "resourceType": "Bundle",
   3
     "type": "searchset",
   4
     "link": [
   5
       {
   6
         "relation": "self",
   7
         "url": "https://stage-dir-ceq.sequoiaproject.org/fhir-stu3/1.0.1/Organization?_format=xml"
   8
       }
   9
     ],
   10
     "total": 1,
   11
     "entry": [
   12
       {
   13
         "resource": {
   14
           "resourceType": "Organization",
   15
           "id": "a05b27f0-f6d3-013d-188b-06d6044a85ae",
   16
           "text": {
   17
             "status": "generated",
   18
             "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Redox Gateway</div>"
   19
           },
   20
           "meta": {
   21
             "versionId": "1",
   22
             "lastUpdated": "2024-03-01T16:21:07Z"
   23
           },
   24
           "identifier": [
   25
             {
   26
               "use": "official",
   27
               "system": "http://www.hl7.org/oid/",
   28
               "value": "2.16.840.1.113883.3.6147.458.2"
   29
             }
   30
           ],
   31
           "active": true,
   32
           "type": [
   33
             {
   34
               "coding": [
   35
                 {
   36
                   "system": "http://hl7.org/fhir/organization-type",
   37
                   "code": "Connection"
   38
                 }
   39
               ]
   40
             }
   41
           ],
   42
           "name": "Redox Gateway",
   43
           "alias": [
   44
             ""
   45
           ],
   46
           "address": [
   47
             {
   48
               "use": "work",
   49
               "type": "both",
   50
               "line": [
   51
                 "25 West Main Street, Suite 500"
   52
               ],
   53
               "city": "Madison",
   54
               "state": "WI",
   55
               "postalCode": "53703",
   56
               "country": "USA"
   57
             }
   58
           ],
   59
           "partOf": {
   60
             "identifier": {
   61
               "use": "official",
   62
               "system": "http://www.hl7.org/oid/",
   63
               "type": {
   64
                 "text": "HCID"
   65
               },
   66
               "value": "2.16.840.1.113883.3.6147.458"
   67
             }
   68
           },
   69
           "contact": [
   70
             {
   71
               "purpose": {
   72
                 "text": "Technical"
   73
               },
   74
               "name": {
   75
                 "use": "official",
   76
                 "text": "Redox, Carequality"
   77
               },
   78
               "telecom": [
   79
                 {
   80
                   "system": "email",
   81
                   "value": "carequality@redoxengine.com",
   82
                   "use": "work"
   83
                 },
   84
                 {
   85
                   "system": "phone",
   86
                   "value": "+16085359501",
   87
                   "use": "work"
   88
                 }
   89
               ]
   90
             },
   91
             {
   92
               "purpose": {
   93
                 "text": "Business"
   94
               },
   95
               "name": {
   96
                 "use": "official",
   97
                 "text": "Redox, Carequality"
   98
               },
   99
               "telecom": [
   100
                 {
   101
                   "system": "email",
   102
                   "value": "support@redoxengine.com",
   103
                   "use": "work"
   104
                 },
   105
                 {
   106
                   "system": "phone",
   107
                   "value": "+16085359501",
   108
                   "use": "work"
   109
                 }
   110
               ]
   111
             }
   112
           ]
   113
         },
   114
         "fullUrl": "https://stage-dir-ceq.sequoiaproject.org/fhir-stu3/1.0.1/Organization/2.16.840.1.113883.3.6147.458.2",
   115
         "search": {
   116
           "mode": "match"
   117
         }
   118
       }
   119
     ]
   120
   }
3. Select one or more organizations from the results list to search.

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

   Copy

   1
   curl --request POST \
   2
     --url https://api.redoxengine.com/fhir/R4/ceq-xcpd:2.16.840.1.113883.3.6147.458.2/Development/Patient/_search \
   3
     --header 'Content-Type: application/x-www-form-urlencoded' \
   4
     --header 'x-purpose-of-use: TREATMENT' \
   5
     --header 'x-sender-organization-id: {{your_oid}}' \
   6
     --header 'x-user-id: {{user_human_readable_id}}' \
   7
     --header 'x-user-role: {{user_role}}' \
   8
     --data 'identifier=http://hl7.org/fhir/sid/us-ssn|010-10-1000' \
   9
     --data birthdate=19980601 \
   10
     --data family=Bixby \
   11
     --data given=Pauline

   FHIR API reference

   Review the Patient schema 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

   Copy

   1
   {
   2
     "resourceType": "Bundle",
   3
     "type": "searchset",
   4
     "total": 1,
   5
     "entry": [
   6
       {
   7
         "resource": {
   8
           "resourceType": "Patient",
   9
           "id": "681d2103-f883-4334-886b-59358580dcb1^2.16.840.1.113883.3.6147.458.2",
   10
           "identifier": [
   11
             {
   12
               "value": "681d2103-f883-4334-886b-59358580dcb1",
   13
               "system": "urn:oid:2.16.840.1.113883.3.6147.458.2"
   14
             }
   15
           ],
   16
           "name": [
   17
             {
   18
               "given": [
   19
                 "pauline"
   20
               ],
   21
               "family": "bixby"
   22
             }
   23
           ],
   24
           "gender": "female",
   25
           "birthDate": "1998-06-01",
   26
           "telecom": [
   27
             {
   28
               "value": "18088675309",
   29
               "system": "phone",
   30
               "use": "home"
   31
             }
   32
           ],
   33
           "address": [
   34
             {
   35
               "line": [
   36
                 "4762 walnut street"
   37
               ],
   38
               "city": "mt. horeb",
   39
               "state": "WI",
   40
               "postalCode": "53572"
   41
             }
   42
           ]
   43
         },
   44
         "search": {
   45
           "mode": "match"
   46
         },
   47
         "fullUrl": "urn:uuid:93fbe6ac-5136-438d-98b2-55ef3d75ef1d"
   48
       }
   49
     ]
   50
   }
3. Repeat these steps for every organization you want to search.

• Request patient documents with FHIR®