Technical Considerations > Carequality Technical Guide
Technical Considerations

Carequality Technical Guide

This guide is meant to assist Redox community members in testing against the sandbox environments of Carequality Implementers. By following the instructions here, you will be able to test the search for patient matches, the identification of various patient documents, and the outbound retrieval of those documents.

You will also be able to test searching and updating the Carequality organizational directory.

Setup

API Authentication

Authentication for Carequality is identical to authentication used for traditional use cases. You can follow the instructions here and the quickstart videos here to learn more.

Subscriptions

Reach out to your Redox Solutions Architect, who can set up the subscription to the Carequality sandbox environments and associated endpoints:

  • Carequality Staging Organizational Directory (XML)
  • Carequality Staging – XCPD
  • Carequality Staging – XCA

Organization

Querying for Organizations

API Details 

The first thing you’ll want to do is to explore the Carequality network. The Organization.Query API gives you the ability to search for organizations on various parameters, such as name, organizational identifier, or date of last update.

Request

First, test the API by making an API call based on the organizational identifier. Let’s pull the Redox organization from the sandbox directory:

Response

You should see this response:

You can try other search variations, such as name-based search:

This should return the same response as the first query.

Explore the Organization.Query API more with different parameters and then head to the next section.

Adding, Updating and Deleting Organizations

API Details 

After you’ve started to see the other organizations on the Carequality network, you can now start to manage your own organization(s) on the network. The Organization.New API gives you the ability to create a new organization or facility.

Creation

The Organization.New API contains all of the information relevant to your or your healthcare organization customer’s institution. Read more below.

After you’ve sent a request in, you will receive a synchronous response indicating creation:

We can also create a subordinate organization using the PartOf field. We’ll create two Redox facilities using this field:

Using this API, we can create an organizational structure for our organization and underlying facilities. Here’s an example you can find in the sandbox:

The organization directory has the flexibility to build detailed hierarchies of two, three, or more levels. Your Redox representative can help provide guidance on best practices of organizational structure. For now, you should create at least one organization.

Updating and Deleting

After you’ve created an organization, you can use the Organization.Update API to change organizational details, such as address or contact information. 

You can also delete the organization within the directory using this API. Note that this does not fully remove all information, but instead marks the facility as inactive.

After a successful update, you’ll receive a response in this format:

Errors

The following scenarios are defined errors by Carequality when adding, modifying, or deleting organizations:

  • 403 – <OID> already exists
  • 403 – Failed to parse request body as XML resource because your request body has to contain at least one identifier element
  • 403 – Failed to parse request body as XML resource because your request body has to contain valid type element.
  • 403 – Failed to parse request body as XML resource because your request body has to contain at least one Contact element. (Implementer only)
  • 403 – Failed to parse request body as XML resource because in your request body, some of endpoints have invalid display name.
  • 403 – id:<ID> is not valid. (on a put/update or delete)
  • 404 – Not Found
  • 500 – Parsing XML Request Error!
  • 500 – Your Organization Source contains duplicate business!

Frequently Asked Questions

What are OIDs? Why are they important?

An OID is a globally unique ISO (International Organization for Standardization) identifier. They are important in the context of Carequality in that they uniquely identify organizations in the network. When creating your organization and facilities, you’ll need to use an OID as the primary identifier. You can read more about OIDs here.

What OID should I use when creating my organization?

If you have a pre-existing OID from another use case, that can be re-used for Carequality. If not, Redox has a base OID and is a Registration Authority, so you can have an OID branch assigned for your use. This will typically be a branch off of the base OID 2.16.840.1.113883.3.6147.458.  

Alternatively, you can register and pay HL7 for an independent OID branch. Work with your Redox representative to determine the best strategy for your organizational identifiers.

PatientSearch

Finding a Patient

API Details

After you’ve used the Organization Data Model to identify external organizations you’re interested in querying, you can use PatientSearch.Query to search that organization to see if your patient exists there.

Metadata

For this API and subsequent transactions, in order to comply with Carequality rules, we need to include some specific information properly identifying the querying user and their organization, as well as the target organization. We use a number of extensions in the Meta tag within the JSON for this purpose.

Request Format

In the body of the request, you should include the patient’s demographics. The table below contains information about test patients available across the Carequality sandbox network:

Example for CRISP

This should result in a response with a match similar to the following:

Here are additional CRISP test patients:

Frequently Asked Questions

What demographic information should I include in my queries?

At a minimum, you should include:

  • First name
  • Last Name
  • Date of Birth
  • Sex
  • Address

It is best practice to include as much information as possible. Most responding systems use advanced matching algorithms that have higher success rates as more information is included. Other valuable data points you may include:

  • Social Security Number
  • Phone numbers
  • Email

ClinicalSummary

Finding the List of Documents

API Details

Once you’ve found a patient’s external ID at an organization, you can use ClinicalSummary.DocumentQuery to determine the list of documents available for the patient.

Metadata

As mentioned for PatientSearch section above, you should include the same extensions in the Meta tag within the JSON.

Request Format

In the body of the request, you must include the patient’s ID and ID Type you received in the response of the PatientSearch. The table below contains information about test patients available across the Carequality sandbox network:

Example for CRISP

This should result in a response with a match similar to the following:

Frequently Asked Questions

I’m getting a lot of documents back on the response. What can I do?

ClinicalSummary.DocumentQuery has a number of useful parameters you can use to limit the number of documents returned or to find the documents that are relevant for you. Not all parameters are supported by all vendors. When supported, using the Visit.StartDate parameter can help you pull documents after a given date of service.

Retrieving a Document

API Details

After you’ve reviewed the list of documents, you can use the ClinicalSummary.DocumentGet to retrieve from an external organization.

Metadata

As mentioned in the previous sections, you should include the same extensions in the Meta tag within the JSON.

Request Format

In the body of the request, you must include the document ID you received in the response of the DocumentQuery. 

Example for CRISP

This should result in a response with a match similar to the following:

Frequently Asked Questions

DocumentGet returns the full XML document. Why is that?Some customers have pre-built capabilities to render XML C-CDA documents. Additionally, there are many open source CDA renderers (such as this one or this one) available that can be useful in viewing the document. We offer the option to return the XML document for this reason. If you’d like the ClinicalSummary contents in JSON format only, let your Redox representative know and they can help configure that setting.