Programming Guide

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

FHIR Resources

The Terminology API abstracts the underlying FHIR resources (CodeSystem, ConceptMap, and ValueSet) that form the basis for the terminology service. In general, these abstractions make the Terminology API easier to understand and use. You can also access the FHIR resources directly through the FHIR Interface.

Reference Code Systems and Value Sets

The Terminology service maintains an up-to-date set of reference code systems (ICD10, SNOMED, LOINC, RxNorm, NDC, etc.) and value sets (CCSR, MedRT, etc). It automatically refreshes itself with periodic updates (typically monthly) published by canonical data sources such as the National Library of Medicine, Regenstrief, AHRQ, CMS, NCQA, and the Veterans Administration. Current and historical code systems are maintained to enable organization of data longitudinally; e.g., historical problems may be coded in ICD9 while recent data is coded in ICD10.

In many situations, the healthcare data you have may not be coded in a standard or consistent manner; or may in fact not be coded at all. Leveraging experience across the entire installed base of Orchestrate adopters–hospitals, labs, state HIEs, payers, and academic health centers–the Terminology service uses advanced domain-specific algorithms to link raw source data–including uncoded free text–to known terminology code systems. For example: problems to ICD10 and SNOMED, labs to LOINC, and medications to RxNorm.

“Reference” value sets are maintained from a variety of sources including the code system publishers (e.g., LOINC, RxNorm), public programs (e.g., CMS), and quality/public health/population health organizations (e.g., AHRQ, CDC, NCQA). A value set will have a collection of codes from one or more reference code systems with a particular common meaning. Value sets have a ‘scope’ based on the publisher/program (e.g., CCSR Category, LOINC-Component), domain (e.g., COVID19), date (e.g., MeasureTerms_MY2020), and/or intended use (e.g., MedRT - May Treat). Value sets are used in terminology/classify and other operations.

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.