Search TEFCA-CommonWell for patient records

After creating an organization record, you can start searching TEFCA-CommonWell for patient records.

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

Searching TEFCA-CommonWell relies on the CommonWell EMPI to identify where on the network a patient can be found, based on the patient’s demographics.

1. 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 development requests; 97f2dc1d-c71b-43a7-a436-9b789d44c804 for production requests).

   What demographic information to include

   We recommend including as much demographic information as possible when you’re searching for a patient. Most TEFCA-CommonWell participants use advanced matching algorithms that have higher success rates when more information is included.

   At a bare minimum, include these in your search:

   • given name
   • family name
   • birthdate

   You should also include any of these extra data points, but it’s up to TEFCA-CommonWell participants whether they rely on them for providing results:

   • gender
   • Social Security number (SSN)
   • ZIP code

   If you don’t include as much patient information as possible, you may find other patients with the same basic demographic information.

   Example: Search for locations in TEFCA-CommonWell

   bash

   Copy

   1
   curl \
   2
   -X POST https://api.redoxengine.com/endpoint \
   3
   -H "Content-Type: application/json" \
   4
   -H "Authorization: Bearer $API_TOKEN" \
   5
   -d '{
   6
       "Meta": {
   7
           "Extensions": {
   8
               "sender-organization-id": {
   9
                   "url": "https://api.redoxengine.com/extensions/sender-organization-id",
   10
                   // The OID represents the organization sending the query. You can use a top-level OID, but if there are multiple levels, it helps to be specific.
   11
                   "string": "{{organization_oid}}"
   12
               },
   13
               "user-id": {
   14
                   "url": "https://api.redoxengine.com/extensions/user-id",
   15
                   // The user ID should be human-readable (typically name, not an ID) and change per query based on the initiating user.
   16
                   "string": "{{user-name}}"
   17
               },
   18
               "user-role": {
   19
                   "url": "https://api.redoxengine.com/extensions/user-role",
   20
                   // Defines the role of the user identified above. This must be a SNOMED CT code.
   21
                   "coding": {
   22
                       "code": "{{user_role}}",
   23
                       "display": "{{human-readable-name-for-code}}"
   24
                   }
   25
               },
   26
               "purpose-of-use": {
   27
                   "url": "https://api.redoxengine.com/extensions/purpose-of-use",
   28
                   // Identifies the purpose of the query, which is almost always TREATMENT. If another purpose of use, other participants likely won't respond.
   29
                   "coding": {
   30
                       "code": "TREATMENT",
   31
                       "display": "Treatment"
   32
                   }
   33
               }
   34
           },
   35
           "DataModel": "PatientSearch",
   36
           "EventType": "LocationQuery",
   37
           # Remove this in Production
   38
           "Test": true,
   39
           "Destinations": [
   40
               {
   41
                   // This is a standard Redox value that varies between environments. Refer to the destination IDs in this article.
   42
                   "ID": "{{destination-id-for-environment}}"
   43
               }
   44
           ]
   45
       },
   46
       "Patient": {
   47
           "Identifiers": [],
   48
      "Demographics": {
   49
         "FirstName": "Redox",
   50
         "MiddleName": null,
   51
         "LastName": "Tester",
   52
         "DOB": "1910-01-01",
   53
         "SSN": "101-01-0001",
   54
         "Sex": "Male",
   55
         "Race": "White",
   56
         "IsHispanic": null,
   57
         "Religion": null,
   58
         "MaritalStatus": "Single",
   59
         "IsDeceased": null,
   60
         "DeathDateTime": null,
   61
         "Language": "en",
   62
         "Citizenship": [],
   63
         "Address": {
   64
           "ZIP": "56789",
   65
         }
   66
       }
   67
       }
   68
   }'

   API reference

   Review the LocationQuery schema for more technical details. Or, review extensions details for any included extensions.

2. The response returns identifiers, including both ID and IDType (i.e., patient assigning authority) and demographic information about the patient, including Organization.Identifiers[].ID.

   CommonWell EMPI results

   With the CommonWell EMPI, results will only be returned for matches that already exist within your own organization’s data set. In other words, demographics results from external repositories won’t be returned unless a demographics match already exists within your own 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.

   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

   Copy

   1
   {
   2
     "Patients": [
   3
       {
   4
         "Identifiers": [
   5
           {
   6
             "ID": "sandbox-tester-123",
   7
             "IDType": "2.16.840.1.113883.3.6147.450.0.2.19301.0.1"
   8
           }
   9
         ],
   10
         "Demographics": {
   11
           "FirstName": "Redox",
   12
           "LastName": "Tester",
   13
           "Sex": "Male",
   14
           "DOB": "1910-01-01",
   15
           "Address": {
   16
             "StreetAddress": "123 Pasture Lane",
   17
             "City": "Madison",
   18
             "State": "WI",
   19
             "ZIP": "56789"
   20
           },
   21
           "PhoneNumber": {
   22
             "Home": "+18088675309"
   23
           }
   24
         },
   25
         "Organization": {
   26
           "Name": "St. Barnabas Hospital",
   27
           "Identifiers": [
   28
             {
   29
               "ID": "2.16.840.1.113883.3.6147.450.0.2.19301.0.1"
   30
             }
   31
           ]
   32
         }
   33
       },
   34
       {
   35
         "Identifiers": [
   36
           {
   37
             "ID": "sandbox-tester-on-sandbox-system-456",
   38
             "IDType": "2.16.840.1.113883.3.6147.450.0.2.19260.0.2"
   39
           }
   40
         ],
   41
         "Demographics": {
   42
           "FirstName": "Redox",
   43
           "LastName": "Tester",
   44
           "Sex": "Male",
   45
           "DOB": "1910-01-01",
   46
           "Address": {
   47
             "StreetAddress": "123 Pasture Lane",
   48
             "City": "Madison",
   49
             "State": "WI",
   50
             "ZIP": "56789"
   51
           },
   52
           "PhoneNumber": {
   53
             "Home": "+18088675309"
   54
           }
   55
         },
   56
         "Organization": {
   57
           "Name": "redox",
   58
           "Identifiers": [
   59
             {
   60
               "ID": "2.16.840.1.113883.3.6147.450.0.2.19260.0.1"
   61
             }
   62
           ]
   63
         }
   64
       }
   65
     ],
   66
     "Meta": {
   67
       "DataModel": "PatientSearch",
   68
       "EventType": "LocationQuery",
   69
       "Source": {
   70
         "ID": "6b8c8f4e-7a69-4575-acb7-58efc8593302",
   71
         "Name": "Integration-CW EETS"
   72
       },
   73
       "Destinations": [
   74
         {
   75
           "ID": "3122bfff-f1fb-4fdf-97de-294f24338229",
   76
           "Name": "CommonWell EMPI [Integration]"
   77
         }
   78
       ],
   79
       "Logs": [
   80
         {
   81
           "ID": "0196f332-ae3c-7ce3-be23-fe2faa35cf7f",
   82
           "AttemptID": "0196f332-ae3c-77fd-aadd-484c95063472"
   83
         }
   84
       ]
   85
     }
   86
   }

   API reference

   Review the LocationQueryResponse schema for full context and technical details.

• Request patient documents