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

HealtheIntent APIs support two methods for authenticating API requests. The simpler, preferred method is bearer token authentication. Alternatively, two-legged OAuth 1.0a authentication is also supported.

To send requests 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 Cerner Central portal. Complete 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 HealtheIntent APIs using a bearer token. This is the simpler means of authentication and is strongly recommended over the OAuth 1.0a workflow described below.

Prerequisites

Using the Bearer Token To Call an API

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

Example Authorization Header Value:

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.

Authenticating Using OAuth

While Cerner strongly recommends that you authenticate HealtheIntent API requests using an OAuth 2.0 bearer token, HealtheIntent also supports accessing APIs using a two-legged OAuth 1.0a authentication workflow. Because this workflow is less common than three-legged authentication, send an OAuth request using a browser or curl before you write any code. This can help you become familiar with the fundamentals of two-legged authentication before you use any third-party libraries, many of which are optimized for the three-legged workflow and may be difficult to use with the two-legged workflow. See the Cerner’s OAuth Specification Reference Page for more information about the authentication workflow below.

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

Prerequisites

Retrieving an Access Token

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

Curl can be used to test retrieving an access token. The examples below 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 (written on multiple lines 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 HealtheIntent API

Using the information in the access token obtained above, an Authorization header can be constructed. This header must be included in every API request.

The following information is needed from the access token response:

The Authorization header must be formatted per the following criteria:

Example authorization header (written on multiple lines 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, for example:

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

Specifying the version in the path is mandatory.

All API modifications are 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 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.

URL Structure

HealtheIntent APIs use the following URL structure:

https://{tenant}.api.{region}.healtheintent.com/{api}/{version}/{resource}

Where:

Example:

https://cernerdemo.api.us-1.healtheintent.com/personnel/v1/personnel-groups/e9d6d83e-3bb6-4942-9789-50c7764847c4

Legacy APIs

Legacy APIs use the following URL structure, which is different than the structure for v1 and later APIs:

https://{tenant}.{solution}.{region}.healtheintent.com/api/{resource}

Where:

Example:

https://cernerdemo.record.us-1.healtheintent.com/api/populations/21702403-8bea-4f05-b805-f209b256e98e/people/registries

Cerner Cloud Regions

Cerner Cloud regions (CCRs) are self-contained, multi-tenant deployments of Cerner Cloud solutions for a specific geographical or political region.

Use the appropriate CCR ID for your HealtheIntent tenant in the hostname when you send requests to the APIs. Some CCRs support alternative IDs for historical purposes. These aliases will continue to be supported for passivity; however, tenants created after February 2020 should use the primary ID exclusively.

Cerner Cloud Region ID Alias
US us-1 us
UK and Egypt emea-1 eu

If you are unsure which CCR your tenant resides in, contact your Cerner engagement leader.

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 IDs 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-1.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.
429 Too Many Requests Your requests are coming too often, or the server is under a heavy load. Try the request again later.
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

Readmission Prevention Service

Risk Assessment Service

Wellness Application Service

Wellness Learning Modules Service

Wellness 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

Classic 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

Patient Engagement

Patient Portal Application Service

Reporting, Analytics, and Data Science

Foster continuous improvement through data-driven decision making.

Business Intelligence

Data Syndication Service

HealtheAnalytics Application Service

Value Optimization

Reduce costs and maximize reimbursements.

Condition Identification Service

Diagnosis Insights Application Service

HCC Service

HealtheInsights Application Service

Registries Service

Quality Measure 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 protected health information (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, and they use an older authorization workflow that clients cannot access in HealtheIntent Console. 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 the future.

What does it mean when an API returns an HTTP 429 status code?

Cerner intentionally rate limits (or throttles) HealtheIntent API requests to help maintain the performance of the services. If the request rate exceeds a safe threshold, an HTTP 429 status code is returned in the response. When a requesting system receives this error, the system should retry the original request. To minimize this error, Cerner recommendeds that the requesting system uses an exponential backoff retry algorithm in which the system waits progressively longer between reattempts.

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 that 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 health care 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 health care 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 in SMART applications, 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, a request 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!