Programming Guide

This guide introduces some basic concepts and workflows that will be important as you begin using the API.

Single Patient

All Convert API operations assume the input data represents a single individual.

Standardization/Uplift

While clinical documents follow various specifications (CCDA/CCD/CDA, HL7, FHIR, etc.) there is enough variation across systems/vendors to make it challenging for consumers (both human and machine) to handle them. The Convert API performs a lossless standardization process (“uplift”) to make its outputs more consistent and suitable for downstream processing.

See Understanding Uplift for details on the standardization/uplift process.

Patient Identifiers

The “to FHIR” operations allow you to specify optional patient identifiers. You may specify either or both types of identifiers.

patientID

The optional patientId query parameter provides a unique resource ID for the patient. In the output bundle, this will be used for Patient.id in the resulting resource.

For example, if the parameters are: /convert/v1/cdatofhirr4?patientID=3aa0bfc6-89fa-400c-a0d1-81a303b85591

The output would include:

"resource": {
                "resourceType": "Patient",
                "id": "3aa0bfc6-89fa-400c-a0d1-81a303b85591",
                ...
            }

patientIdentifier and patientIdentifierSystem

The optional patientIdentifier and patientIdentifierSystem query parameters specify a business identifier, such as an MRN or MPI identifier. Both parameters must be specified together.

In the output bundle, these parameters will be used for the first identifier field in the resulting Patient resource. Other identifiers from the original payload are also included as subsequent entries in the identifier list. The patientIdentifierSystem specifies the identifier’s system URI.

For example, if the parameters are: convert/v1/cdatofhirr4?patientidentifier=XYZ123456&patientIdentifierSystem=urn:oid:1...

The output would include:

"resource": {
                "resourceType": "Patient",
                "identifier": [
                  {
                      "use": "usual",
                      "type": {
                          "coding": [
                              {
                                  "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                                  "code": "MR"
                              }
                          ]
                      },
                      "system": "urn:oid:1.2.840.000.1.13.246.2.7.2.688879.7700",
                      "value": "XYZ123456"
                  },
                ...
            }

Output FHIR R4 Bundles

All of the “to FHIR” operations (including Combine FHIR Bundles) return a FHIR R4 Bundle containing the input data converted into FHIR resources. The bundle will be of type collection.

OperationOutcomes

These bundles include an OperationOutcome resource. An OperationOutcome is a collection of issue elements detailing what was parsed from the input, as well as any problems with the conversion. See Operation Outcomes for details.

Resource IDs

The Convert API will generate unique logical ids for all resources in a FHIR bundle that were converted from the input. Resources within a bundle may refer to other resources within the same bundle.

For example, a HL7-to-FHIR conversion may generate a Patient resource, and some Observation resources that reference back to that patient.

Patient:

      "resourceType": "Patient",
      "id": "202b89d5-8187-4131-9863-deb197954dbc",
                
Observation:
        
      "resourceType": "Observation",
      "id": "2.93e9a8b7befa4345b477717d00d125e5",
      
      "subject": {
        "reference": "Patient/202b89d5-8187-4131-9863-deb197954dbc"
      },

Convert API operations are stateless, and different requests are independent of one another. Submitting the same input information to the API multiple times will result in different logical ID elements being generated for the equivalent input concept. In the example above, that means the Patient and Observation will be assigned a different auto-generated id field each time. Business identifiers are retained if sent in the input data.

Codes/Codings/CodeableConcepts

As part of the conversion process, the Convert API will use the Terminology service to standardize input codes.

FHIR Code elements (such as Patient.gender or Condition.clinicalStatus) represent enumerations with a set of possible values. In these situations, the code in the FHIR bundle will be the equivalent input field translated into an equivalent value in the enumeration. An extension element will be added (e.g., Patient._gender, Condition._clinicalStatus) that contains the input code as sent represented as a Coding. For example:

CDA Patient:

    administrativeGenderCode code="F" codeSystem="ExampleNamespace" codeSystemName="ExampleNamespace" displayName="Female"

FHIR Patient:

    "gender": "female",
    "_gender": {
    extension": [{
        ...
        "coding": [{
          "system": "http://rosetta.careevolution.com/codes/Proprietary.ExampleNamespace/Gender",
          "code": "F",
          "display": "Female",

In addition to the data directly present in the input, CodeableConcepts may have additional codings representing the standardized reference codes from the Terminology API. These added codings can be identified by the userSelected: false property. For more information, see Terminology Uplift.

REST API

This API is a REST-based interface, which means that applications make requests by accessing specific URLs using HTTP. One of the hallmarks of REST is that the API calls are stateless, meaning each request is a single, self-contained operation to analyze or transform the provided data.

Some segments of the API URLs use curly braces {} to indicate that they are variables conveying information about the specific resource you wish to access. For example, the URL /terminology/v1/classify/{type}/batch lets you specify the resource type.

Base URL

The base endpoint for the Orchestrate APIs is:

https://api.careevolutionapi.com

For example:

https://api.careevolutionapi.com/terminology/v1/classify/condition

In the API reference, the base URL is usually omitted for brevity, and only the bolded part given.

API Versioning

Versioning is built into the URLs. For example, the URL terminology/v1 is the root for all “version 1” terminology-based services, with resources like terminology/v1/standardize/condition and terminology/v1/classify/medication.

Required Headers

Every API call requires the following fields in the HTTP request header:

Authorization

No additional authorization is required beyond the API key header (see required headers).

Error Handling

The response header for each request contains a status code indicating whether the request was successful. Common status codes you will encounter are:

Operation Outcomes

In addition to the HTTP status codes, many of the FHIR-based APIs will include an OperationOutcome resource in their output. An OperationOutcome is a collection of issue elements detailing what was parsed from the input, as well as any problems with the conversion. The issue severity, code, and details elements will describe the specifics of the issue and its location within the input data. The issue code will be one of the following values from the FHIR IssueType list:

• Information - Informative only; requires no follow up or action. For example: the number of conditions parsed from the input.
• Warning - Likely requires no follow up; flags conversions where portions of the input may be disregarded or ignored. For example: a duplicate data element was found and ignored.
• Error - Likely requires follow up; flags lossy conversions or assumptions made to generate the output. For example: a required field was missing so a default value was assumed, or an element was not parseable and removed from the output.
• Fatal - The input data is not usable as given. For example: the XML or JSON is malformed.

For example:

{
  "resource": {
    "resourceType": "OperationOutcome",
    "issue": [
      {
        "severity": "warning",
        "code": "processing",
        "details": {
          "text": "Labs: Missing description in the reference dictionary for #labgroup_3. Line Number - 662, XPath - ClinicalDocument/component/structuredBody/component/section/entry/organizer/code/originalText/reference"
        }
      },
      {
        "severity": "information",
        "code": "informational",
        "details": {
          "text": "Processed 2 entries from Encounters section."
        }
      },
      ... (additional issues if applicable)
    ]
  }
}

When using the development sandbox, issues from the OperationOutcome will automatically be highlighted in the alert area for easy reference.

Rate Limits

The API has a rate limiting feature to preserve stability for all customers. Users who send too many API requests within a short timeframe will receive a 429: Too Many Requests error.

The API limits you to a number of requests per month. The specific number depends on your account tier. You can check your limit and usage in the Developer Portal.

If you find you need a higher rate limit, contact us to discuss upgrading your account.