NAV Navbar
Logo cerner

Introduction

Welcome to the HealtheIntent open development documentation. The HealtheIntent open development ecosystem allows access to population health based concepts through RESTful APIs. These APIs are meant to be consumed by other systems/applications in a B2B (Business to business) context. As such, there is no user-level authorization or filtering applied; it is expected that the systems/applications interacting with these APIs are applying the appropriate authorization controls for end users.

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 support bearer tokens. Alternatively, all APIs also support two-legged OAuth 1.0a authentication.

In order to make calls to the APIs you will need a Cerner system account which 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:

Once the new account is approved, work with your HealtheIntent Engagement Leader or submit an eService ticket to request that the account be granted access to the appropriate APIs and resources.

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 later.

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.

Example authorization header value (multiline 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. Since 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 uCern Wiki for more information about the authentication flow below.

For detailed OAuth 1.0a documentation see the OAuth 1.0a spec.

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 appears in the URI like so:

  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 identifiers. Moving forward, all new APIs will be 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.

Since 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 Person IDs

Many use cases for the HealtheIntent APIs involve the integration of person-level information from HealtheIntent into a user’s workflow in a different system. In order for the HealtheIntent APIs to send information for the correct person, you need to define the unique person in your request using a record ID. However, the systems sending the requests do not (and should not) store HealtheIntent internal identifiers in their own databases.

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

Looking Up a HealtheIntent Person Using a Local System Identifier

This is the preferred method for determining a HealtheIntent person ID, but it requires the system from which you are sending the request to know the internal person identifier 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 the longitudinal person records, the data sources’ original local identifiers are maintained in the person data, and can still be used to identify the person. These local identifiers are usually back-end database identifiers rather than user-facing IDs such as medical record numbers (MRNs) or financial numbers (FINs). For example, for data from Cerner Millennium, the local identifier would be the Cerner Millennium person ID (MPI) rather than an MRN.

In addition to the local identifier, the data partition identifier must also be included in the request for the HealtheIntent person ID. This parameter uniquely identifies the namespace that the local person identifier belongs to. Cerner provides the data partition ID when the data source and partition are being onboarded, and the ID remains constant for all look-up requests. More information on the person lookup request can be found in the documentation here.

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 identifiers for multiple different electronic health records (EHRs). In such a situation, you may need to look up the person identifier using the data partition ID for the registration system even if you are integrating the person 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 uCern 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 Person 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 Your 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 Your request could not be understood by the server, often due to bad 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 doesn’t 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 Something went wrong on our end.

HealtheIntent API Catalog

Platform APIs

Legacy APIs

HealtheLife Framework SDK

FAQs

General

How do I find a person’s record ID?

You can find the HealtheIntent record ID by using a local person identifier or by searching for the person based on their attributes. For more information on this process, see the Looking Up Person 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.

SMART and FHIR

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 apps 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 app 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 apps 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 app negotiates the user authentication and authorization, while the app 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 are not required to be used only within a SMART application, and SMART apps can be built using non-FHIR APIs. However, when you build a SMART app that uses FHIR APIs — that is, a “SMART on FHIR” app — that app is theoretically “pluggable” into any EHR or other system that provides both a SMART container and FHIR APIs.

Why aren’t HealtheIntent’s APIs FHIR APIs?

HealtheIntent is a cloud-native platform that exists outside the context of any particular EHR, so HealtheIntent’s APIs are already reusable across systems. For example, the call to retrieve registry information for a person is the same regardless of whether you make the request from within a Cerner EHR, a non-Cerner EHR, a patient portal, or a standalone app. Therefore, SMART apps built using HealtheIntent APIs are already “pluggable” in the same manner as SMART on FHIR apps.

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, shoehorning 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.

Are you ever going to provide FHIR APIs for HealtheIntent?

We may create FHIR APIs for certain key features of HealtheIntent that line up well with FHIR resources, including many of the concepts in the longitudinal person record and the forthcoming longitudinal care plan. Any new FHIR APIs that we may create for HealtheIntent would be additions to our existing APIs, not replacements for them.

Support

Community

The Ignite API Community on uCern 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!

Note: This page includes links to external resources. These resources are provided for reference purposes and should be used with caution. Contact your Cerner support team for more information about third-party content.