Search TEFCA-CommonWell for patient records

• (Optional) Test sending these requests with our TEFCA-CommonWell sandbox. Learn about our TEFCA-CommonWell sandbox.

  Use curl for technical validation

  You can copy our code examples and send the test requests with curl (learn more about curl) 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 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.
  • 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
  • Troubleshoot OAuth API key errors

• Be familiar with the following terms and concepts to send your queries to TEFCA-CommonWell:

  TEFCA-CommonWell terms to know

  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.

  Metadata for TEFCA-CommonWell queries

  This table contains the metadata fields for Redox data models if you’re querying 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.
  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.
  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.

  Destination IDs for TEFCA-CommonWell

  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	3122bfff-f1fb-4fdf-97de-294f24338229	7fd005ac-d788-40c5-b4e8-b57bb8e310a9
  Query for/create/update/delete an organization	3122bfff-f1fb-4fdf-97de-294f24338229	7fd005ac-d788-40c5-b4e8-b57bb8e310a9
  Search for a clinical summary/document	cf1dca0e-98de-432b-8c9a-dd039816df0e	79981c00-b9c4-40a9-9844-01980e6e524e
  Save patient details to your repository	3122bfff-f1fb-4fdf-97de-294f24338229	7fd005ac-d788-40c5-b4e8-b57bb8e310a9
  Save documents to your repository	This is specific to your organization. Redox provides the correct ID.	This is specific to your organization. Redox provides the correct ID.

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.
• Locate specific sites to directly query. After locating a site, use the organization OID in the location query response to request patient records.

Follow these steps to search:

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