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:
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 the Framework.
As a result, the patient ID in the data on demand repository isn't the same as the patient ID in the Framework. To find the network ID for a patient, send a PatientSearch.Query with the patient demographics to the Redox gateway: 2.16.840.1.113883.3.6147.458.2
.
You can copy the code examples we provide and send the test requests with curl
(learn more about curl) instead of Postman. Keep in mind though that you need to remove the comments from the code examples (starting with //
) and replace any variables (e.g., {{variable here}}
) to use them. Also, note that some of the code examples are abbreviated, so be mindful of that if you're copying them for your own use.
If you're operating in Canada, you must tweak the Redox hostname slightly. All you need to do is add a ca
in that URL like this: https://api.ca.redoxengine.com
.
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.
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 further down for specifics. | For most patient searches, this is a Redox destination within record locator service. For document searches, this is a Carequality destination. For responding with information about your patients, this is your own document repository. |
Meta.FacilityCode | The OID of the organization you wish to query. | This isn't necessary for patient searches with record locator service. |
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 are providing services for. |
Meta.Extensions.sender-organization-id | The organizational OID to identify your organization as the one sending the request. | |
Meta.Extensions.user-id | Contains either the name of the user sending the request or the name of 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 which case, the query runs in the background on the provider’s behalf. |
Meta.Extensions.user-role | Defines the role of the user sending the request. | You must use a SNOMED value for this field. Check out the US Health Information Knowledgebase for a list of available SNOMED values. |
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 digital record retrieval. |
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:
Request purpose | Staging ID | Production ID |
---|---|---|
Query for/create/update/delete an organization | a07afe3b-d247-4415-827f-6837707e1b8b | 5d0fd248-6c52-4ad9-b907-ae10bf2dcc39 |
Search for a patient with record locator service | adf917b5-1496-4241-87e2-ed20434b1fdb | 97f2dc1d-c71b-43a7-a436-9b789d44c804 |
Search for a patient within a specific organization | 1ca254a8-8d42-4593-abb4-b21399d9de57 | 6391b961-55ae-430b-a789-cf575f03fca0 |
Search for a clinical summary/document | ec745338-8849-43ad-a7ce-4bc5bf1d8b89 | 628cbf79-1156-4923-b9d0-285906160ed6 |
Save patient details and documents to your repository | This is specific to your org—you can find the correct ID in the digital record retrieval wizard. | This is specific to your org—you can find the correct ID in the digital record retrieval wizard. |
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.
curl
, send a PatientSearch.Query request with the patient's demographics to the Redox gateway (2.16.840.1.113883.3.6147.458.2
).
curl \-X POST https://api.redoxengine.com/endpoint \-H "Content-Type: application/json" \-H "Authorization: Bearer {{access token}}" \-d '{"Meta": {"Extensions": {"sender-organization-id": {"url": "https://api.redoxengine.com/extensions/sender-organization-id",# This should be the OID representing you as an organization. If you have multiple levels, it helps to be specific# but you can also just use your top-level"string": "{{organization_oid}}"},"user-id": {"url": "https://api.redoxengine.com/extensions/user-id",# This should change per query and should be a human-readable ID for the user (typically name, not an actual ID)"string": "{{user_human_readable_id}}"},"user-role": {"url": "https://api.redoxengine.com/extensions/user-role",# Depends on the user above, this is a SNOMED CT code# See here: https://www.hl7.org/fhir/valueset-practitioner-role.html"coding": {"code": "{{user_role}}",# This is set for the default code (112247003), but if you have a different code, this should change"display": "Medical Doctor"}},"purpose-of-use": {"url": "https://api.redoxengine.com/extensions/purpose-of-use",# Almost ALWAYS treatment -> depends on the app purpose, but typically this is treatment# If it wasn't, other organizations on Carequality likely wouldn't respond# To use this, you have to participate in Carequality, which is why you also have to push data"coding": {"code": "TREATMENT","display": "Treatment"}}},"DataModel": "PatientSearch","EventType": "Query",# Remove this in Production"Test": true,"Destinations": [{# This value is standard Redox Meta structure and will vary between environments# See the Carequality FAQ for Production values -- you're all set for sandbox testing"ID": "{{rls_query_destination}}"}]},"Patient": {"Demographics": {# These will change for whatever information you have, see our API documentation for supported fields"FirstName": "Lacy523","LastName": "Waelchi213","DOB": "2014-05-19","Sex": "Male","Address": {"StreetAddress": "418 Rice Ranch Apt 17","City": "Easton","State": "Massachusetts"}}}}'
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).
curl \-X POST https://api.redoxengine.com/endpoint \-H "Content-Type: application/json" \-H "Authorization: Bearer {{access token}}" \-d '{"Meta": {"Extensions": {"sender-organization-id": {"url": "https://api.redoxengine.com/extensions/sender-organization-id",# This should be the OID representing you as an organization. If you have multiple levels, it helps to be specific# but you can also just usee your top-level"string": "{{organization_oid}}"},"user-id": {"url": "https://api.redoxengine.com/extensions/user-id",# This should change per query and should be a human-readable ID for the user (typically name, not an actual ID)"string": "{{user_human_readable_id}}"},"user-role": {"url": "https://api.redoxengine.com/extensions/user-role",# Depends on the user above, this is a SNOMED CT code# See here: https://www.hl7.org/fhir/valueset-practitioner-role.html"coding": {"code": "{{user_role}}",# This is set for the default code (112247003), but if you have a different code, this should change"display": "Medical Doctor"}},"purpose-of-use": {"url": "https://api.redoxengine.com/extensions/purpose-of-use",# Almost ALWAYS treatment -> depends on the app purpose, but typically this is treatment# If it wasn't, other organizations on Carequality likely wouldn't respond# To use this, you have to participate in Carequality, which is why you also have to push data"coding": {"code": "TREATMENT","display": "Treatment"}}},"DataModel": "PatientSearch","EventType": "LocationQuery",# Remove this in Production"Test": true,"Destinations": [{# This value is standard Redox Meta structure and will vary between environments# See the Carequality FAQ for Production values -- you're all set for sandbox testing"ID": "{{rls_query_destination}}"}]},"Patient": {"Identifiers": [{# These will always change based on the previous search response. This only ever expects one identifier at this time"IDType": "2.16.840.1.113883.3.6147.458.2","ID": "9ab85b7b-3946-4cfa-977f-5fbc84334ac8"}]}}'
{"Meta": {"DataModel": "PatientSearch","EventType": "LocationQuery","Extensions": {"sender-organization-id": {"url": "https://api.redoxengine.com/extensions/sender-organization-id","string": "2.16.840.1.113883.3.6147.458.5420.1.1.2"},"user-id": {"url": "https://api.redoxengine.com/extensions/user-id","string": "{{user_human_readable_id}}"},"user-role": {"url": "https://api.redoxengine.com/extensions/user-role","coding": {"code": "112247003","display": "Medical Doctor"}},"purpose-of-use": {"url": "https://api.redoxengine.com/extensions/purpose-of-use","coding": {"code": "TREATMENT","display": "Treatment"}},"task-id": {"url": "https://api.redoxengine.com/extensions/task-id","string": "6cd7a70d-024f-4239-898a-5a3745242948"},"task-status": {"url": "https://api.redoxengine.com/extensions/task-status","string": "Success"}},"EventDateTime": "2021-12-08T21:47:05.931Z","Message": {"ID": 12672017218},"Source": {"ID": "7f296bb4-83fd-498d-92f3-a76960648788"},"Destinations": [{"ID": "adf917b5-1496-4241-87e2-ed20434b1fdb","Name": "Outbound RLS"}],"Logs": [{"ID": "c7addcc6-8206-4d3d-986b-1ce0bd1002e0","AttemptID": "754b8cdd-3022-4fdc-8613-cdba52db4ff0"}]},"Patients": [{"Identifiers": [{"ID": "d5a61983-5ef8-4d31-a1ce-9a92b1f098f9","IDType": "2.16.840.1.113883.3.6147.458.2"}],"Organization": {"Identifiers": [{"ID": "2.16.840.1.113883.3.6147.458.2","IDType": "OID"}]}}]}
The Meta.Extensions.task-status.string
field contains a status of either Active
or Success
.
Status | Definition | Results |
---|---|---|
Active | The process is asynchronously collecting locations. | The Patients array populates with any partial results as they become available. |
Success | The process has completed and all possible locations were found. | Any available results have been returned. If the Patients array is empty, it means no patients were found. |
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.
To review the results of your search again later, you can provide the value returned in Meta.Extensions.task-id.string
on subsequent requests.
If you run a new search with the same patient demographics within a 24-hour period, you see the same results. Record Locator Service doesn't trigger a new search to your connections unless you have new or modified patient demographics.
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.
curl \-X POST https://api.redoxengine.com/endpoint \-H "Content-Type: application/json" \-H "Authorization: Bearer {{access token}}" \-d '{"Meta": {"DataModel": "Organization","EventType": "Query","Destinations": [{# This value is standard Redox Meta structure and will vary between environments# See the Carequality FAQ for Production values -- you're all set for sandbox testing"ID": "{{organization_query_destination}}","Name": "Redox Carequality - Organization Directory (XML)"}]},"Directory": "Carequality",# For all of the below, pass null if you're not searching that style, otherwise behavior will try to search the most exact## Identifier is only if you know the exact identifier of the organization, which is rare, but used for example here (finding your own org)"Identifier": {"ID": "{{organization_oid}}","IDType": "OID"},# There are two "SearchType"'s "exact" and "contains" - use as desired with the "Value" field the search param"NameSearch": {"SearchType": null,"Value": null},# You can use state to look in a specific state, or use the radius search to search from a zip code# Using both together should not be done"State": null,"RadiusSearch": {"ZipCode": null,"Radius": null},# This can be used to page results"Index": null,"Limit": 20}'
{"Meta": {"DataModel": "Organization","EventType": "Query","Source": {"ID": "7f296bb4-83fd-498d-92f3-a76960648788"},"Message": {"ID": 12693372849},"Destinations": [{"ID": "5de9d0e0-91f6-4b89-9bfb-461a6966d93a","Name": "Carequality Organizational Directory"}],"Logs": [{"ID": "e6e74f98-ff08-4b1a-aedb-b0e53226948b","AttemptID": "15c2375b-fdf7-420e-ab92-29b2676981b9"}]},"Directory": "Carequality","Organizations": []}
The OID is found in the FacilityCode
field of the Organization.QueryResponse that you received in the previous step.
curl \-X POST https://api.redoxengine.com/endpoint \-H "Content-Type: application/json" \-H "Authorization: Bearer {{access token}}" \-d '{"Meta": {"Extensions": {"sender-organization-id": {"url": "https://api.redoxengine.com/extensions/sender-organization-id",# This is the OID that represents you as an organization. If you have multiple levels, it helps to be specific# but you can also just use your top-level."string": "{{organization_oid}}"},"user-id": {"url": "https://api.redoxengine.com/extensions/user-id",# This should change per request and should be a human-readable ID for the user (typically name, not an actual ID)."string": "{{user_human_readable_id}}"},"user-role": {"url": "https://api.redoxengine.com/extensions/user-role",# This is a SNOMED CT code that relates to the user above.# See here: https://www.hl7.org/fhir/valueset-practitioner-role.html."coding": {"code": "{{user_role}}",# This is set for the default code (112247003), but this should change if you have a different code."display": "Medical Doctor"}},"purpose-of-use": {"url": "https://api.redoxengine.com/extensions/purpose-of-use",# Almost ALWAYS treatment -> depends on the app purpose, but typically this is treatment.# If it wasn't, other organizations on Carequality likely wouldn't respond.# To use this, you have to participate in Carequality, which is why you also have to push data."coding": {"code": "TREATMENT","display": "Treatment"}}},"DataModel": "PatientSearch","EventType": "Query",# Removed in production"Test": true,"Destinations": [{# This value is standard Redox Meta structure and will vary between environments.# See the Carequality FAQ for Production values -- you're all set for sandbox testing."ID": "{{standard_patient_destination}}"}],# From the previous Organization.Query, this should be the Organization's OID that you want to search.# So if there are 4 organizations you're interested in, you must make 4 of these requests to find the patient at that location.# However, watch out for duplicates by looking at the Endpoints values in the Organization results, to see if they have# the same gateway.# Below, we use Redox for example."FacilityCode": "2.16.840.1.113883.3.6147.458.2"},"Patient": {"Demographics": {# Populate these fields based on your patient's information. See our API documentation for supported fields."FirstName": "Adolfo","LastName": "Kessler","DOB": "2002-10-31","SSN": "999-55-2115","Sex": "Male","Address": {"City": "Madison","State": "Wisconsin","ZIP": "53711"}}}}
{"Patient": {"Demographics": {"Address": {"County": null,"Country": null,"ZIP": "53711","State": "wisconsin","City": "madison","StreetAddress": "602 schiller junction suite 68"},"EmailAddresses": [],"PhoneNumber": {"Work": null,"Mobile": "+15556533376","Home": "+15556533376"},"Sex": null,"DOB": "2002-10-31","LastName": "kessler","FirstName": "adolfo","SSN": ""},"Identifiers": [{"IDType": "2.16.840.1.113883.3.6147.458.2","ID": "45e5fadd-0496-4e48-be26-a06d78f8e950"}]},"Meta": {"DataModel": "PatientSearch","EventType": "Query","Message": {"ID": 12721022314},"Source": {"ID": "d9c19117-7778-47fd-9f55-b3bccc4055f8"},"Destinations": [{"ID": "1ca254a8-8d42-4593-abb4-b21399d9de57","Name": "Carequality Sandbox - XCPD"}],"Logs": [{"ID": "0a4eb252-cb7a-4349-b0a5-5ccc53be2e37","AttemptID": "95f2c3bd-8660-45b4-a73b-a3543908d4c2"}]}}
Basic information
How-to
Troubleshooting