NAV Navbar
Logo cerner
Ruby Shell

CareAware Data Ingestion API v1

CareAware is the Cerner platform for connecting patient and provider medical devices with electronic health records (EHRs). CareAware can be integrated with both Cerner and non-Cerner EHRs and uses the CareAware iBus architecture to provide plug-and-play connectivity for devices. Device data from CareAware iBus instances can be sent to HealtheIntent to be ingested using this API. The data is processed onto the HealtheIntent platform continuously and in near-real time. Each CareAware iBus instance is represented by a unique data source ID in HealtheIntent and can produce multiple types of records. The record types are defined by Cerner, and the records use an Apache Avro schema. See the Apache Avro website for more information about the schema.

URL: https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1

Data Sources

Data sources are the systems that contribute data to the HealtheIntent platform. CareAware data sources must be connected to the CareAware service to contribute data. See the Data Source API for more information about HealtheIntent data sources.

Retrieve a List of CareAware Data Sources

Example Request:


require 'httparty' # Using HTTParty 0.16.2
require 'json'

headers = {
  'Authorization' => '<auth_header>',
  'Accept' => 'application/json'
}

result = HTTParty.get('https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/data-sources', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X GET https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/data-sources \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

Example response

{
  "items": [
    {
      "id": "0b8edc65-c9e1-4035-9040-9568442ff6b4",
      "careawareSourceType": "string"
    }
  ],
  "totalResults": 1,
  "firstLink": "https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/data-sources?offset=0&limit=20",
  "lastLink": "https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/data-sources?offset=0&limit=20"
}

GET /data-sources

Retrieves a list of all data sources that are connected to the CareAware service.

Parameters

Parameter In Type Required Default Description Accepted Values
offset query integer(int32) false 0 The number of results to skip from the beginning of the list of results (typically for the purpose of paging). The minimum offset is 0. There is no maximum offset. -
limit query integer(int32) false 20 The maximum number of results to display per page. The minimum limit is 1. The maximum limit is 100. -

Response Statuses

Status Meaning Description Schema
200 OK A collection of data sources DataSources
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error

Update a CareAware Data Source

Example Request:


require 'httparty' # Using HTTParty 0.16.2
require 'json'

headers = {
  'Authorization' => '<auth_header>',
  'Accept' => 'application/json'
}

result = HTTParty.put('https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/data-sources/0b8edc65-c9e1-4035-9040-9568442ff6b4', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X PUT https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/data-sources/0b8edc65-c9e1-4035-9040-9568442ff6b4 \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

PUT /data-sources/{dataSourceId}

Adds or updates a CareAware data source. If the data source is not already connected to the CareAware service, it is connected. If it is already connected, it is updated.

Parameters

Parameter In Type Required Default Description Accepted Values
dataSourceId path string true N/A The ID of a data source. -

Response Statuses

Status Meaning Description Schema
204 No Content No Content None
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error

Retrieve a Single CareAware Data Source

Example Request:


require 'httparty' # Using HTTParty 0.16.2
require 'json'

headers = {
  'Authorization' => '<auth_header>',
  'Accept' => 'application/json'
}

result = HTTParty.get('https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/data-sources/0b8edc65-c9e1-4035-9040-9568442ff6b4', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X GET https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/data-sources/0b8edc65-c9e1-4035-9040-9568442ff6b4 \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

Example response

{
  "id": "0b8edc65-c9e1-4035-9040-9568442ff6b4",
  "careawareSourceType": "string"
}

GET /data-sources/{dataSourceId}

Retrieves a single data source that is connected to the CareAware service.

Parameters

Parameter In Type Required Default Description Accepted Values
dataSourceId path string true N/A The ID of a data source. -

Response Statuses

Status Meaning Description Schema
200 OK A single data source DataSource
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error

Data Partitions

CareAware data that is ingested onto the platform is transformed until its shape is normalized and its terminology is standardized, at which point it is published in data partitions and ready to be used by other platform services, solutions, and applications. All single-tenant data sources have a single data partition. All multi-tenant data sources have a data partition for each unique CareAware iBus tenant ID. Partitions will be owned by the same tenant who owns the data source.

Retrieve a List of CareAware Data Partitions

Example Request:


require 'httparty' # Using HTTParty 0.16.2
require 'json'

headers = {
  'Authorization' => '<auth_header>',
  'Accept' => 'application/json'
}

result = HTTParty.get('https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/data-sources/0f6e6e66-376f-4e52-a051-5a452db1fd8c/data-partitions', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X GET https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/data-sources/0f6e6e66-376f-4e52-a051-5a452db1fd8c/data-partitions \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

GET /data-sources/{dataSourceId}/data-partitions

Retrieves a list of all the data partitions that are connected to the CareAware Data Ingestion service.

Parameters

Parameter In Type Required Default Description Accepted Values
dataSourceId path string true N/A The unique ID of the data source. -
caTenantId query string false N/A The tenant ID within a multi-tenant CareAware iBus Cloud instance. -
conceptMappingConsumerId query string false N/A The unique Concept Mapping ID of the consumer that is used to search for the mapping. -
offset query integer(int32) false 0 The number of results to skip from the beginning of the list of results (typically for the purpose of paging). The minimum offset is 0. There is no maximum offset. -
limit query integer(int32) false 20 The maximum number of results to display per page. The minimum limit is 1. The maximum limit is 100. -

Response Statuses

Status Meaning Description Schema
200 OK A collection of data partitions DataPartitions
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error

Update a Single CareAware Data Partition

Example Request:




require 'httparty' # Using HTTParty 0.16.2
require 'json'

headers = {
  'Authorization' => '<auth_header>',
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = HTTParty.put('https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/data-sources/0f6e6e66-376f-4e52-a051-5a452db1fd8c/data-partitions/5b6e6095-1023-46f9-9521-ccf0ae68ab54', headers: headers)

print JSON.pretty_generate(result)




# You can also use wget
curl -X PUT https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/data-sources/0f6e6e66-376f-4e52-a051-5a452db1fd8c/data-partitions/5b6e6095-1023-46f9-9521-ccf0ae68ab54 \
-H 'Authorization: {auth_header}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'

PUT /data-sources/{dataSourceId}/data-partitions/{dataPartitionId}

Adds a CareAware data partition or updates a data partition to be connected to the CareAware Data Ingestion service. If the data partition is not already connected to the CareAware Data Ingestion service, it is added. If it is already connected, it is updated.

Parameters

Parameter In Type Required Default Description Accepted Values
dataSourceId path string true N/A The unique ID of the data source. -
dataPartitionId path string true N/A The unique ID of the data partition. -
body body putDataSourcesDatasourceidDataPartitions true N/A No description -

Response Statuses

Status Meaning Description Schema
204 No Content No Content None
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error
409 Conflict Conflict Error

Retrieve a Single CareAware Data Partition

Example Request:


require 'httparty' # Using HTTParty 0.16.2
require 'json'

headers = {
  'Authorization' => '<auth_header>',
  'Accept' => 'application/json'
}

result = HTTParty.get('https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/data-sources/0f6e6e66-376f-4e52-a051-5a452db1fd8c/data-partitions/5b6e6095-1023-46f9-9521-ccf0ae68ab54', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X GET https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/data-sources/0f6e6e66-376f-4e52-a051-5a452db1fd8c/data-partitions/5b6e6095-1023-46f9-9521-ccf0ae68ab54 \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

GET /data-sources/{dataSourceId}/data-partitions/{dataPartitionId}

Retrieves a single data partition that is connected to the CareAware Data Ingestion service.

Parameters

Parameter In Type Required Default Description Accepted Values
dataSourceId path string true N/A The unique ID of the data source. -
dataPartitionId path string true N/A The unique ID of the data partition. -

Response Statuses

Status Meaning Description Schema
200 OK A single data partition DataPartition
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error

Record Types

Record types (for example, location or device) are defined by Cerner and specify the format to which records’ keys and values must adhere in order for HealtheIntent to parse the records and identify key information.

Record types are versioned. When the specification changes, a new record type version is created for the schema. Record type versions are compatible with past and future versions of the same type, and the key type for each record type is the same across versions. If changes are incompatible, a new record type is created.

Each record is uniquely identified by a record key. A record key is a pairing or multiple pairings that uniquely identify the record. The key must conform to the key type specified for the pairings of keys and values record type. For example, if the record type has a key type defined as [ {“name”: “eventType”, “type”: “string”}, {“name”: “event”, “type”: “string”} ], the following key would conform to the key type: { “eventType”: “ABC”, “event”: “DEF” }. The values in record keys are Avro binary-encoded values that are Base64-encoded. The values must be in Avro binary format and adhere to the record type specification.

Records also are versioned. Record versions help determine the order of records that are published with the same key. Examples of common record versions include timestamps in milliseconds or logical clock values. The version value cannot be negative.

Retrieve a List of Record Types

Example Request:


require 'httparty' # Using HTTParty 0.16.2
require 'json'

headers = {
  'Authorization' => '<auth_header>',
  'Accept' => 'application/json'
}

result = HTTParty.get('https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/record-types', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X GET https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/record-types \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

Example response

{
  "items": [
    {
      "id": "location",
      "name": "CareAware Location",
      "description": "A location represents a place inside a medical facility.",
      "keyType": [
        {
          "name": "ca_location",
          "type": "int64"
        }
      ]
    }
  ],
  "totalResults": 1,
  "firstLink": "https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/record-types?offset=0&limit=20",
  "lastLink": "https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/record-types?offset=0&limit=20"
}

GET /record-types

Retrieves a paginated list of record types for which records can be published.

Parameters

Parameter In Type Required Default Description Accepted Values
offset query integer(int32) false 0 The number of results to skip from the beginning of the list of results (typically for the purpose of paging). The minimum offset is 0. There is no maximum offset. -
limit query integer(int32) false 20 The maximum number of results to display per page. The minimum limit is 1. The maximum limit is 100. -

Response Statuses

Status Meaning Description Schema
200 OK A collection of record types RecordTypes
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error

Retrieve a Single Record Type

Example Request:


require 'httparty' # Using HTTParty 0.16.2
require 'json'

headers = {
  'Authorization' => '<auth_header>',
  'Accept' => 'application/json'
}

result = HTTParty.get('https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/record-types/location', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X GET https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/record-types/location \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

Example response

{
  "id": "location",
  "name": "CareAware Location",
  "description": "A location represents a place inside a medical facility.",
  "keyType": [
    {
      "name": "ca_location",
      "type": "int64"
    }
  ]
}

GET /record-types/{recordTypeId}

Retrieves a single record type.

Parameters

Parameter In Type Required Default Description Accepted Values
recordTypeId path string true N/A The ID of the record type. -

Response Statuses

Status Meaning Description Schema
200 OK A single record type RecordType
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error

Retrieve a List of Record Type Versions

Example Request:


require 'httparty' # Using HTTParty 0.16.2
require 'json'

headers = {
  'Authorization' => '<auth_header>',
  'Accept' => 'application/json'
}

result = HTTParty.get('https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/record-types/location/versions', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X GET https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/record-types/location/versions \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

Example response

{
  "items": [
    {
      "version": "1.1"
    }
  ],
  "totalResults": 1,
  "firstLink": "https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/record-types/location/versions?offset=0&limit=20",
  "lastLink": "https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/record-types/location/versions?offset=0&limit=20"
}

GET /record-types/{recordTypeId}/versions

Retrieves a paginated list of versions for the given record type.

Parameters

Parameter In Type Required Default Description Accepted Values
recordTypeId path string true N/A The ID of the record type. -
offset query integer(int32) false 0 The number of results to skip from the beginning of the list of results (typically for the purpose of paging). The minimum offset is 0. There is no maximum offset. -
limit query integer(int32) false 20 The maximum number of results to display per page. The minimum limit is 1. The maximum limit is 100. -

Response Statuses

Status Meaning Description Schema
200 OK A collection of versions RecordTypeVersionListItems
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error

Retrieve a Single Record Type Version

Example Request:


require 'httparty' # Using HTTParty 0.16.2
require 'json'

headers = {
  'Authorization' => '<auth_header>',
  'Accept' => 'application/json'
}

result = HTTParty.get('https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/record-types/location/versions/1.1', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X GET https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/record-types/location/versions/1.1 \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

Example response

{
  "recordTypeId": "location",
  "version": "1.1",
  "name": "CareAware Location",
  "description": "A location represents a place inside a medical facility.",
  "keyType": [
    {
      "name": "ca_location",
      "type": "int64"
    }
  ],
  "schema": "ew0KICAgICAidHlwZSI6ICJyZWNvcmQiLA0KICAgICAibmFtZXNwYWNlIjogImNvbS5leGFtcGxlIiwNCiAgICAgIm5hbWUiOiAiRm9vIiwNCiAgICAgImZpZWxkcyI6IFsNCiAgICAgICB7ICJuYW1lIjogImJhciIsICJ0eXBlIjogInN0cmluZyIgfQ0KICAgICBdDQp9IA=="
}

GET /record-types/{recordTypeId}/versions/{versionId}

Retrieves a single record type version.

Parameters

Parameter In Type Required Default Description Accepted Values
recordTypeId path string true N/A The ID of the record type. -
versionId path string true N/A The version of the record type. -

Response Statuses

Status Meaning Description Schema
200 OK A record type version RecordTypeVersion
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error

Contributed Records

Contributed records (sometimes referred to as published or uploaded records) are records that are sent to HealtheIntent and are ready to be processed onto the platform.

Publish Records

Example Request:




require 'httparty' # Using HTTParty 0.16.2
require 'json'

headers = {
  'Authorization' => '<auth_header>',
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = HTTParty.post('https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/data-sources/31d76349-ddc5-405e-b980-66c3e598334c/contributed-records', headers: headers)

print JSON.pretty_generate(result)




# You can also use wget
curl -X POST https://cernerdemo.api.us.healtheintent.com/careaware-ingestion/v1/data-sources/31d76349-ddc5-405e-b980-66c3e598334c/contributed-records \
-H 'Authorization: {auth_header}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'

Example response

{
  "successfulRecordCount": 1
}

POST /data-sources/{dataSourceId}/contributed-records

Publishes a collection of records for ingestion.

Parameters

Parameter In Type Required Default Description Accepted Values
dataSourceId path string true N/A The ID of the data source in which the record exists. -
body body array[object] true N/A The collection of records to publish. -

Response Statuses

Status Meaning Description Schema
200 OK If all of the records properly adhere to their record type specifications and are successfully published, a response is sent that indicates the number of records published is equal to the number of records in the request. ContributedRecordsResponse
400 Bad Request Bad Request. The record or records were not published due to issues with the request. All records in the request should be reattempted. The response includes error details with a reason field that can help identify the issue. The following reasons are possible, among others:
- keyTranslationError A record includes values that do not adhere to the record type key specification.
- missingField The request is missing required fields.
- invalidField A field in the JSON body is incorrect in some way, for example, the data type is incorrect.
- recordNotParseable A record does not adhere to the provided record type schema.
- recordTypeNotFound The record type ID and version do not correspond to a registered record type instance.
Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error
413 Payload Too Large Payload Too Large. The request exceeded the maximum threshold. Break up the request by sending fewer records across multiple requests then try again. Error

Schema Definitions

RecordTypes

Name Type Required Description Accepted Values
items [RecordType] true An array containing the current page of results. -
totalResults integer(int32) false The total number of results for the specified parameters. -
firstLink string true The first page of results. -
lastLink string false The last page of results. -
prevLink string false The previous page of results. -
nextLink string false The next page of results. -

RecordType

Name Type Required Description Accepted Values
id string true The ID of a specific record type. -
name string false A human-readable name for the record type. -
description string false A description of what the record type represents. -
keyType [KeyTypeElement] true The structure of the key attribute for records of this type. This is an ordered array of one or more elements. The elements are ordered from generic to more specific to allow systems to identify similar records across multiple record types by matching the initial elements of the key. -

KeyTypeElement

Name Type Required Description Accepted Values
name string true The ID of the key type element. This ID is used as the key value in a record’s key collection. -
type string true The data type or format of key values of this type. string, int64, uuid

Error

Name Type Required Description Accepted Values
code integer(int32) true The HTTP response status code that represents the error. -
message string true A human-readable description of the error. -
errorDetails [ErrorDetail] false A list of additional error details. -

ErrorDetail

Name Type Required Description Accepted Values
domain string false A subsystem or context where an error occurred. -
reason string false A codified value that represents the specific error that caused the current error status. -
message string false A human-readable description of an error. -
locationType string false The location or type of the field that caused an error. query, header, path, formData, body
location string false The name of the field that caused an error. -

RecordTypeVersionListItems

Name Type Required Description Accepted Values
items [RecordTypeVersionListItem] true An array containing the current page of results. -
totalResults integer(int32) false The total number of results for the specified parameters. -
firstLink string true The first page of results. -
lastLink string false The last page of results. -
prevLink string false The previous page of results. -
nextLink string false The next page of results. -

RecordTypeVersionListItem

Name Type Required Description Accepted Values
version string true The ID of a specific version of the record type. -

RecordTypeVersion

Name Type Required Description Accepted Values
recordTypeId string true The ID of a specific record type. -
version string true The ID of a specific version of the record type. -
name string false A human-readable name for the record type. -
description string false A description of what the record type represents. -
keyType [KeyTypeElement] true The structure of the key attribute for records of this type. This is an ordered array of one or more elements. The elements are ordered from generic to more specific to allow systems to identify similar records across multiple record types by matching the initial elements of the key. -
schema string true A Base64-encoded, JSON-formatted Avro schema to which records of this type must adhere. -

Record

Name Type Required Description Accepted Values
recordType RecordTypeVersionReference true A reference to the record type resource that defines the format to which the record’s key and value must adhere. -
key object true A set of key and value pairs that uniquely identify the record. The key must conform to the keyType specified by the record type that the recordType attribute references. For example, if the record type defines its key type as:
[ {"name": "eventType", "type": "string"}, {"name": "event", "type": "string"} ]
then an example of a conforming key would be:
{ "eventType": "ABC", "event": "DEF" }
-
version integer(int32) true The version of the record identified by the provided key. The version assists in determining the order of records that have been published with the same key. Common version values might be timestamps in milliseconds or logical clock values. The version value cannot be negative. -
value string true An Avro binary-encoded value that is Base64-encoded. The value must be in an Avro binary format and adhere to the schema identified by the recordType specification. -

RecordTypeVersionReference

Name Type Required Description Accepted Values
id string true The ID of a specific record type. -
version string true The ID of a specific version of the record type. -

ContributedRecordsResponse

Name Type Required Description Accepted Values
successfulRecordCount integer(int32) true The number of records that were successfully published. This can be used for verification purposes. -

DataSources

Name Type Required Description Accepted Values
items [DataSource] true An array containing the current page of results. -
totalResults integer(int32) false The total number of results for the specified parameters. -
firstLink string true The first page of results. -
lastLink string false The last page of results. -
prevLink string false The previous page of results. -
nextLink string false The next page of results. -

DataSource

Name Type Required Description Accepted Values
id string true The ID of a specific data source. -
careawareSourceType string false The careawareSourceType for the data source -

DataPartitions

Name Type Required Description Accepted Values
items [DataPartition] true An array containing the current page of results. -
totalResults integer(int32) false The total number of results for the specified parameters. -
firstLink string true The first page of results. -
lastLink string false The last page of results. -
prevLink string false The previous page of results. -
nextLink string false The next page of results. -

DataPartition

Name Type Required Description Accepted Values
dataPartition object true The unique ID of the data partition. -
caTenantId string false The tenant ID inside of a multi-tenant CareAware Cloud iBus instance. -
conceptMappingConsumerId string false The unique Concept Mapping ID of the consumer that is used to search for the mapping. -

putDataSourcesDatasourceidDataPartitions

Name Type Required Description Accepted Values
caTenantId string false The tenant ID inside of a multi-tenant CareAware Cloud iBus instance. -