NAV Navbar
Logo cerner

Introduction

Welcome to the HealtheIntent Open Development Documentation website. HealtheIntent open development services allow access to population health concepts using RESTful APIs. These APIs are meant to be used by other systems and applications in a business to business (B2B) context. As such, user-level authorization and filtering are not applied; Cerner expects that the systems and applications interacting with these APIs apply the appropriate authorization controls for users.

Getting Started

Authentication

The HealtheIntent APIs support two different mechanisms for authenticating API calls. The newer and simpler authentication mechanism is bearer token authentication. All but one of the existing APIs support bearer token authentication; the Data Collector API does not. Alternatively, all APIs also support two-legged OAuth 1.0a authentication.

To make calls to the APIs, you need a Cerner system account that includes a bearer token and a set of OAuth credentials called the consumer key and consumer secret.

Requesting a System Account

A system account can be requested through the CernerCentral administrative portal. Fill out the request form with the following information:

See Configure System Account for HealtheIntent System Authentication in the Reference Pages on Cerner Wiki for more information.

Configuring API Authorization

When the system account is approved, add the system account and grant the account authorization for the appropriate APIs and resources in HealtheIntent Console. See the following resources on Cerner Wiki for more information, or contact your HealtheIntent engagement leader or log a service record (SR) in eService to request authorization:

Authenticating Using a Bearer Token

This section provides basic steps for accessing protected APIs using a bearer token. This is the simpler means of authentication as compared to the OAuth 1.0a flow described below.

Prerequisites

Using the Bearer Token to Call a Protected API

The Authorization header is used for calling protected APIs. The header can be built using the structure below. The built header should then be added when calling protected APIs.

See the example below of an authorization header value. It is written in multiple lines for readability.

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.

Authenticating Using OAuth

This section provides basic steps for accessing protected APIs using a two-legged OAuth 1.0a authentication flow. Because this flow is less common than three-legged authentication, you should test making an OAuth call using a browser or curl before writing any code. This will help you get familiar with the fundamentals of two-legged authentication before using any third-party libraries, many of which are optimized for the three-legged flow and may be difficult to use with the two-legged flow. See Cerner’s OAuth specification in the Reference Pages on Cerner Wiki for more information about the authentication flow below.

For detailed OAuth 1.0a documentation, see the OAuth 1.0a specification on the OAuth Community Site.

Prerequisites

Retrieving an Access Token

Make an HTTPS POST to the OAuth access token URL as follows:

Curl can be used to test retrieving an access token. The following examples will use 32dc21c-8ece-4ada-89b3-c152713f0575 as an example consumer key and L5ZeC0mVyot2C-KQlkXg5egglZsIphaC as an example consumer secret. You would replace these values with your own consumer key and secret.

Example request (multiline for readability):

curl -X POST -d "oauth_consumer_key=32dc21c-8ece-4ada-89b3-c152713f0575\
&oauth_signature_method=PLAINTEXT\
&oauth_signature=L5ZeC0mVyot2C-KQlkXg5egglZsIphaC%26"\
 https://api.cernercare.com/oauth/access

Example response:

oauth_token=ConsumerKey%3D332dc21c-8ece-4ada-89b3-c152713f0575%26ExpiresOn%3D1461779242%26HMACSecrets%3DL-RNB8AAMQM6iIdiP9m091f-JwYpcsJKj18SJNaGVqBtx7t0NA1SLVxm0cKvatdK4o3cb5sHPpHsr8rcNSofmzbX39sS2MsQc81cdjr0_HyBlKgC2rIy_2TRzjGvytsv0B5daJUmuA-EPW6U0-o7BQ%253D%253D%26KeysVersion%3Dfcecee6b-0c23-4df5-a332-799f9a515c16%26RSASHA1%3DOg5rz-58zVBJ924PSgOGoT34vOBOBNsbYNn_i1HijNDhbb_H3PbQXIFKvAcSU636hdqVT2eDeoRgz7aDitlmkvpFZuK3yi-cEYSFXIXuRmagHWeVYQs8A8I3WdZ-yritAwwfTESOGqXmomP6hC-2wiR_WFzqbGJcFcGVqdv2VqzMPgtd3CGz7KoTlOKSacBPq0AHGcu_PCm3oIlrgNReUZdm89MG7MkWNeGFOxiwMHKUzr4oZqwRehZb6LdpYrBJ0vYu94Qg-V_0UME9b7RIASXLtcTtducEREpDCwQZ0MqMsL0mXQ20dDfDD7t7AUziJZELZIDjTB4tPNZD3-aukQ%253D%253D&oauth_token_secret=Qsk0auN5DOu3C9IbkHq2jE5Q6hMI3Nd_&oauth_session_handle=mEYrqIb_zM8sNpReS8AFwvSNOef5Tz2K&oauth_expires_in=3600&oauth_authorization_expires_in=86400

Using the Access Token to Call a Protected API

Given an access token it is now possible to call a protected API.

The following information will be needed from the access token response:

The Authorization header is used for calling protected APIs. The header can be built using the structure below. The built header should then be added when calling protected APIs.

Example authorization header (multiline for readability):

OAuth oauth_token="ConsumerKey%3D332dc21c-8ece-4ada-89b3-c152713f0575%26ExpiresOn%3D1461779242%26HMACSecrets%3DL-RNB8AAMQM6iIdiP9m091f-JwYpcsJKj18SJNaGVqBtx7t0NA1SLVxm0cKvatdK4o3cb5sHPpHsr8rcNSofmzbX39sS2MsQc81cdjr0_HyBlKgC2rIy_2TRzjGvytsv0B5daJUmuA-EPW6U0-o7BQ%253D%253D%26KeysVersion%3Dfcecee6b-0c23-4df5-a332-799f9a515c16%26RSASHA1%3DOg5rz-58zVBJ924PSgOGoT34vOBOBNsbYNn_i1HijNDhbb_H3PbQXIFKvAcSU636hdqVT2eDeoRgz7aDitlmkvpFZuK3yi-cEYSFXIXuRmagHWeVYQs8A8I3WdZ-yritAwwfTESOGqXmomP6hC-2wiR_WFzqbGJcFcGVqdv2VqzMPgtd3CGz7KoTlOKSacBPq0AHGcu_PCm3oIlrgNReUZdm89MG7MkWNeGFOxiwMHKUzr4oZqwRehZb6LdpYrBJ0vYu94Qg-V_0UME9b7RIASXLtcTtducEREpDCwQZ0MqMsL0mXQ20dDfDD7t7AUziJZELZIDjTB4tPNZD3-aukQ%253D%253D",
oauth_consumer_key="332dc21c-8ece-4ada-89b3-c152713f0575",
oauth_signature_method="PLAINTEXT",
oauth_signature="L5ZeC0mVyot2C-KQlkXg5egglZsIphaC%26Qsk0auN5DOu3C9IbkHq2jE5Q6hMI3Nd_"

Versioning

HealtheIntent APIs use a path-based versioning strategy, where the version for a given API is included in the URI like the following example:

  https://cernerdemo.api.us.healtheintent.com/personnel/v1

Specifying the version in the path is mandatory.

All API modifications will be passive within a given version. When nonpassive changes are necessary, a new version will be introduced.

Examples of passive changes:

Examples of nonpassive changes:

Legacy (Pre-1.0) APIs

Until recently, HealtheIntent APIs did not have explicit version IDs. Going forward, all new APIs are versioned. The pre-1.0 “legacy” APIs will continue to be supported (and may be enhanced passively), but they will eventually be deprecated in favor of newer, versioned APIs.

URI Structure

URIs for HealtheIntent APIs generally adhere to one of two structures. The structure used by a specific API can be found in the documentation for that API.

Because HealtheIntent is a multi-tenant platform, both structures include a client mnemonic in the hostname to identify the HealtheIntent client for which API calls are being made.

Pre-1.0 APIs

Older, pre-1.0 APIs use the following base URI structure:

  https://{client-mnemonic}.{solution}.healtheintent.com/api

Where:

Examples:

Version 1.0+ APIs

Newer APIs from version 1.0 and beyond use the following base URI structure:

  https://{client-mnemonic}.api.us.healtheintent.com/{api-name}/{version}

Where:

Examples:

Note that while in the former structure APIs are mostly aligned with HealtheIntent solutions, in the latter they are more aligned with platform capabilities (the concepts upon which HealtheIntent solutions are built).

Looking Up Patient IDs

Many use cases for HealtheIntent APIs involve the integration of patient information from HealtheIntent into a user’s workflow in a different system. Because patient IDs in HealtheIntent are not the same as the IDs used to represent those patients in the systems that contribute data to the platform, it is necessary to first translate the system’s local patient ID to the ID of the corresponding patient in HealtheIntent.

Therefore, in most integrations, the first step to sending requests to the HealtheIntent APIs is to retrieve the HealtheIntent patient ID for the patient in the context of the user’s workflow. The HealtheIntent patient ID can then be used to make further API requests. You can locate a patient’s HealtheIntent patient ID by using a local system ID. It is also possible to search for a patient using attributes such as name or alias, but this method is not guaranteed to return a single patient. For example, if you search by name or date of birth, more than one patient could match the search criteria.

Looking Up a HealtheIntent Patient Using a Local System’s Patient ID

This is the preferred method for determining a HealtheIntent patient ID, but it requires the system from which you are sending the request to know the internal patient ID for the data source that is contributing data to HealtheIntent. This is usually only the case if the system issuing the API requests is itself a HealtheIntent data source. When the data from the source is ingested into the platform and aggregated into longitudinal patient records, the data sources’ original local ID are maintained in the patient data and can still be used to identify the patient. These local IDs are usually back-end database IDs rather than user-facing IDs such as medical record numbers (MRNs) or financial numbers (FINs). For example, for data from Cerner Millennium, the local ID would be the Cerner Millennium patient ID (MPI) rather than an MRN.

In addition to the local ID, the data partition ID must also be included in the request for the HealtheIntent patient ID. This parameter uniquely identifies the namespace that the local patient ID belongs to. Cerner provides the data partition ID when the data source and partition are onboarded, and the ID remains constant for all look-up requests. See the HealtheIntent Patient ID Lookup section of the Patient API page for more information about the patient look-up request.

Note on Multiple Data Partitions:

In rare cases, a single source system is divided into multiple data partitions in HealtheIntent, meaning that a single system may need to use multiple data partition IDs. For example, a centralized registration system may assign IDs for multiple different electronic health records (EHRs). In such a situation, you may need to look up the patient ID using the data partition ID for the registration system even if you are integrating the patient information into a connected EHR with a different data partition ID. If you are unsure whether this is the case for your system, contact your Cerner support team. See Understand Multi-Tenant Data Sources in HealtheIntent in the Reference Pages on Cerner Wiki for more information.

Two data partitions

Patient API Example

Example Request
  require 'httparty'

  HTTParty.get(
    'https://cernerdemo.api.us.healtheintent.com/patient/v1/populations/1424e81d-8cea-4d6b-b140-d6630b684a58/patient-id-lookup?dataPartitionId=e1f0e864-97e4-4c3b-bd7c-91864760cd12&sourcePersonId=3019123&sourcePersonId=1597456&sourcePersonId=1234566',
    headers: {'Authorization' => '<auth_header>'}
  )
Example Response
{
  "items": [
    {
      "sourcePersonId": "3019123",
      "patient": {
        "id": "a2f6a16d-1331-4ccc-8f70-6c4d953b1234"
      }
    },
    {
      "sourcePersonId": "1597456",
      "patient": {
        "id": "b3g6a16d-1331-4ccc-8f70-6c4d953b8765"
      }
    },
    {
      "sourcePersonId": "1234566",
      "patient": {
        "id": "c4e6a16d-1331-4ccc-8f70-6c4d95323456"
      }
    }
  ]
}

Legacy HealtheRecord API Example

Example Request
  require 'httparty'

  HTTParty.get(
    'https://cernerdemo.record.healtheintent.com/api/populations/1424e81d-8cea-4d6b-b140-d6630b684a58/data_partitions/877307a0-b5f5-4a01-9d4b-9fead6bcf788/empi_lookup?id=12345',
    headers: {
      'Authorization' => '<auth_header>',
    }
  )
Example Response
  {
    "response": {
      "fields": [
        {
          "field_name": "empi_person_id",
          "field_value": "<HealtheIntent Patient ID>"
        }
      ],
      "errors": {}
    }
  }

Searching for a HealtheIntent Person

It is also possible to search for people in HealtheIntent based on attributes such as name, date of birth, and alias. See the Person Search documentation for a complete list.

Example Request with Name
  require 'httparty'

  HTTParty.get(
    'https://cernerdemo.record.healtheintent.com/api/populations/1424e81d-8cea-4d6b-b140-d6630b684a58/people?q=roberson',
    headers: {
      'Authorization' => '<auth_header>',
      'Content-Type' => 'application/json'
    }
  )
Example Request with Alias
  require 'httparty'

  HTTParty.get(
    'https://cernerdemo.record.healtheintent.com/api/populations/1424e81d-8cea-4d6b-b140-d6630b684a58/people?alias_value=156695&assigning_authority=1.2.3.4.5.6.7.8.9.10.1'
    headers: {
      'Authorization' => '<auth_header>',
      'Content-Type' => 'application/json'
    }
  )
Example Response
{
  "persons": [
    {
      "id": "a2f6a16d-1331-4ccc-8f70-6c4d953ba70b",
      "gender": "Female",
      "prefix": null,
      "suffix": null,
      "full_name": null,
      "given_names": [
        "Analisa"
      ],
      "family_names": [
        "Roberson"
      ],
      "formatted_name": "Roberson, Analisa",
      "date_of_birth": "1934-08-20",
      "date_of_death": null,
      "deceased": false,
      "address": {
        "street_addresses": [
          "38190 Pine Alley"
        ],
        "city": "CHICAGO",
        "county_or_parish": null,
        "state_or_province": "IL",
        "postal_code": "60634",
        "country": null
      },
      "telecoms": [],
      "emails": [],
      "record_ids": [
        {
          "data_partition_id": "877307a0-b5f5-4a01-9d4b-9fead6bcf788",
          "person_id": "151579"
        }
      ]
    }
  ],
  ...
  "more_results": true,
  "total_results": 209
}

HTTP Status Codes

Cerner uses standard HTTP status codes to indicate the success or failure of an API request. Generally, codes in the 2xx range indicate success, codes in the 4xx range indicate a problem with your request, and codes in the 5xx range indicate a problem on our end. The HealtheIntent APIs use the status codes below. More details about the possible responses for each endpoint are listed in the Responses sections on the pages for the APIs.

Code HTTP Definition Meaning
200 Success Everything worked as expected.
201 Created The item was created.
204 No Content Returned for PUT, POST, or DELETE requests when you should not expect a response body to be returned.
304 Not Modified Returned for conditional ‘GET’ requests when nothing has changed since the previous request.
400 Bad Request The request was not understood by the server, often due to incorrect syntax or parameters.
401 Unauthorized Your request did not have valid authentication credentials.
403 Forbidden Your request had valid authentication credentials, but those credentials are not allowed to complete the requested operation.
404 Not Found The resource you requested does not exist.
409 Conflict Your request failed due to a conflict with the current state of the resource.
412 Precondition Failed Your request contained preconditions that were not met.
422 Unprocessable Entity The content type and syntax of the request are correct, but the server was unable to process the instructions.
500 Internal Server Error An error occurred on our end.

Services

Care Planning and Coordination

Coordinate care planning and delivery across the continuum of care.

Care Management Service

Longitudinal Plan Service

Provider Service

Risk Assessment Service

Wellness Application Service

Wellness Learning Modules Service

Wellness Service

Wellness User Registration Service

Consumer Engagement

Engage patients and consumers as active partners in their own health.

Application Experience Service

Consumer Engagement Service

Salesforce Integration Service

Wellness Application Service

Wellness Campaign Service

Content

Catalog ontology contexts and other reference information.

Ontology Service

Education Service

Core

Instantiate and configure the basic platform components required to run other services and applications.

Master Person Management Service

Kernel Service

Data Ingestion

Push data to the platform via APIs.

CareAware Data Ingestion Service

Data Source Service

Prime Data Ingestion

Universal Data Ingestion Service

Identity

Manage the attributes and relationships of the people and organizations affecting the health of your populations.

Consumer Service

Organization Service

Personnel Service

Specialty Service

Longitudinal Record

Collate and expose longitudinal patient records.

Cohort Service

Chart Search Service

Longitudinal Record Service

Reporting, Analytics, and Data Science

Foster continuous improvement through data-driven decision making.

Data Syndication Service

HealtheAnalytics Application Service

Value Optimization

Reduce costs and maximize reimbursements.

HCC Service

Registries Service

HealtheLife Framework SDK

FAQs

General FAQs

Do you have a demo or sandbox environment?

HealtheIntent is a tenant-scoped system, and Cerner maintains a tenant with the mnemonic cernerdemo that functions as a developer sandbox. The cernerdemo tenant is a full production-level tenant that is populated with realistic synthetic data that can be used for demonstration purposes. Cerner often recommends that you develop your integration using the cernerdemo tenant first, as the APIs respond in the same way they do for a client tenant but you cannot expose PHI. The code examples included in the API documentation often include IDs and response data from the cernerdemo tenant; however, because the data for the tenant is frequently updated, some of the example IDs may be invalid.

If you want to use the cernerdemo tenant to design and test your implementation, contact your Cerner representative or log an SR in eService. Clients control access to the APIs for their tenants in HealtheIntent Console, but Cerner owns and controls access to the cernerdemo tenant. See Configuring API Authorization for more information.

How do I determine a patient’s ID in HealtheIntent?

You can find the HealtheIntent record ID by using a local patient ID or by searching for the patient based on their attributes. For more information about this process, see the Looking Up Patient IDs section above.

Is an additional license required to use the HealtheIntent APIs?

If you are already a HealtheIntent client, no additional license, contract, or fee is required to use the APIs associated with the solutions you license. Note that if you are using the APIs to integrate with a third-party system, the vendor of that system may require licensing or fees for the integration.

Can I send requests to HealtheIntent APIs from Cerner Millennium?

Yes, Cerner Command Language (CCL) scripts can be used to create, retrieve, update, or remove HealtheIntent information using the HealtheIntent APIs. See Understand HealtheIntent API CCL Requests in the Reference Pages on Cerner Wiki for more information.

How can I request a new feature?

You can request new features in the Ideas space on uCern Connect for the solution with which the API aligns. For example, to request a feature for an API that retrieves data from the longitudinal record, log an idea on the HealtheRecord Ideas page.

Why are some APIs labeled legacy?

The APIs that are labeled legacy were developed before a clear versioning strategy was in place. The legacy APIs will continue to be supported for the foreseeable future, but Cerner recommends that all new integrations use one of the versioned APIs where possible. See the Versioning section for more information.

Why do the provided example responses not always match what I see when making the equivalent request in the cernerdemo tenant?

The data and IDs in the cernerdemo tenant are not static. While we try to keep the example IDs and response data in sync with what is currently in cernerdemo, they are not guaranteed to be. To find valid IDs in cernerdemo, use one of the list endpoints. For example, to find valid allergy IDs in cernerdemo, call the /allergies endpoint.

Is there an SDK for the HealtheIntent APIs in my programming language?

Cerner does not currently provide language-specific SDKs for the HealtheIntent APIs but plans to in future.

Authentication FAQs

How many system accounts do I need?

Each system account should represent a distinct system. For many tenants, this equates to one account per environment in the sense that you have different instances of a system (for example, development and production instances). When in doubt, create a new system account; this is because authentication and authorization are scoped by system account. Having a separate account for each system limits the potential impact if a given account is compromised: one can be shut off without affecting others.

Will my bearer token expire?

Bearer tokens do not expire automatically and should be rotated manually on a regular basis. You should also rotate your bearer token when an administrator account is removed or whenever you suspect that the credentials might be compromised. See Rotating the System Account Secret in System Account Management on Cerner Wiki for information about how to rotate your bearer token, and see Accessing Cerner’s Web Services Using A System Account Bearer Token and Overview of System Account Management on Cerner Wiki for more information about bearer tokens and System Account Management generally.

I sent my bearer token or secret over email. How do I rotate my secrets?

You should never send your bearer token or OAuth secret using unsecured methods such as email. If you believe a secret might be compromised, you should immediately rotate your secrets. See Rotating the System Account Secret in System Account Management on Cerner Wiki and the Authenticating Using a Bearer Token section above for more information.

SMART and FHIR FAQs

What are FHIR APIs?

Fast Healthcare Interoperability Resources (FHIR) is a health information data interchange format that can be used as an interoperability standard for electronic health records (EHRs). FHIR allows healthcare data to be accessed easily outside the context of the core system, such as by mobile apps or embeddable applications that extend the functionality provided by an EHR vendor. Applications built to rely on FHIR resources can be used with any system that supports the FHIR standard, eliminating the need for custom application development for each EHR platform. See the FHIR resources on the Health Level Seven (HL7) website for more information.

What is SMART?

SMART (Substitutable Medical Applications and Reusable Technologies) is an open, standards-based technology platform whose primary purpose is to support portable, interoperable healthcare applications. SMART applications can be standalone web applications, or they may be embedded in the context of other systems, such as an EHR, data warehouse, or patient portal. In the embedded model, the SMART container that encapsulates the application determines the user authentication and authorization, while the application itself provides the functionality and the user experience.

What is SMART on FHIR?

As described above, FHIR and SMART are two different technologies that fulfill two separate purposes. FHIR APIs do not have to be used only within a SMART application, and SMART applications can be built using non-FHIR APIs. However, when you build a SMART application that uses FHIR APIs (that is, a “SMART on FHIR” application) that application can theoretically be inserted into any EHR or other system that provides both a SMART container and FHIR APIs.

Why are HealtheIntent’s APIs not FHIR APIs?

HealtheIntent is a cloud-native platform that exists outside the context of any particular EHR, so HealtheIntent APIs are already reusable across systems. For example, the call to retrieve registry information for a patient is the same regardless of whether you make the request from a Cerner EHR, a non-Cerner EHR, a patient portal, or a standalone application. Therefore, SMART applications built using HealtheIntent APIs can already be inserted into workflows in the same manner as SMART on FHIR applications.

Much like the designers of FHIR, we subscribe to core values of simplicity, readability, usability, and consistency in our APIs. Because FHIR is primarily a standard for EHR information and not population health information, at least right now, some of the data we expose through the HealtheIntent APIs would not fit cleanly into FHIR resources. Paradoxically, forcing HealtheIntent data into FHIR models and vendor extensions would make many of the APIs less simple and usable, not more so, and would not provide any advantage in terms of reusability.

Does Cerner plan to provide FHIR APIs for HealtheIntent?

Cerner may create FHIR APIs for certain key features of HealtheIntent that align well with FHIR resources, including many of the concepts in the longitudinal patient record and the longitudinal care plan. Any new FHIR APIs that Cerner creates for HealtheIntent would be additions to existing APIs, not replacements.

Support

Community

The Ignite APIs Community on uCern Connect is the best place to connect with Cerner engineers and other developers using the HealtheIntent APIs. Ask questions, share tips and tricks, make suggestions, and show off your work!