NAV Navbar
Logo cerner
ruby shell

Data Syndication API

Data syndication facilitates the bulk delivery of HealtheIntent data. It provides direct, low-level, asynchronous access to the information that HealtheIntent solutions create, curate, and operate against. This API is used mainly to populate a data warehouse or other third-party data store for research, reporting, or analytical activities.

Release Considerations: The Data Syndication endpoints are available at both of the URLs below; however, as of December 5, 2018, the /syndication path is deprecated and should not be used. Any existing scripts that use /syndication should be updated to use /data-syndication. This note will be removed or updated when the /syndication path no longer is supported.

Terminology

Term Definition
feed types The types of available data sets, for example, Longitudinal Record.
feeds The set of data that you want to receive on a schedule, for example, Longitudinal Record for population ABC.
bundles The output of a feed, for example, Changes to the Longitudinal Record for population ABC between 2018-04-01 and 2018-04-02.
channel types The ways you can have bundles delivered, for example, DOWNLOAD.
channels Specifies that you want to receive a feed’s bundles using a particular channel type and provides any necessary configuration for the channel type. For example, a channel could specify that you want to receive your Longitudinal Record for Population ABC feed using the DOWNLOAD channel type.
deliveries The status of delivering a particular bundle using a particular channel. For example, you would use the Deliveries endpoint to determine whether the archive file for changes to the Longitudinal Record for population ABC between 2018-04-01 and 2018-04-02 bundle is available for you to download.

To help understand these concepts, consider an analogy to the delivery of physical products. Suppose you want to have a newspaper, the Cerner Post, delivered to you by the postal service every day, but that you are only interested in the classifieds section. In this example:

Feed Types

The following feed types are currently available:

Name Mnemonic
Hierarchical Condition Categories Analytics hcc-analytics
Longitudinal Record EDW long-record-edw
Millennium ODS millennium-ods
Outcomes Analytics outcomes-analytics
Personnel Analytics personnel-analytics

Channel Types

The following channel types are currently available:

Name Description
DOWNLOAD Channels the data into archive files that can be downloaded using this API.
S3 Channels the data into a specified Amazon S3 bucket.

Data Retention

Download Channel Type

Due to the size of archive files, it is not practical for Cerner to retain them indefinitely. Each archive file produced using the DOWNLOAD channel type is available for three weeks from the time when the delivery is completed, as indicated by the deliveredAt timestamp in the corresponding delivery object. After three weeks, Cerner deletes the file and the delivery’s status is changed to PURGE_IN_PROGRESS or PURGED to indicate that the file can no longer be downloaded. If a system attempts to retrieve the delivery after that time, a 404 HTTP status code (Not Found) is sent.

S3 Channel Type

Cerner does not manage files after they are delivered using the S3 channel type to client-owned Amazon S3 buckets. If you use the S3 channel type, you are responsible for defining your data retention policy for the delivered files.

Getting Started

Authorization

Only authorized system accounts are able to access endpoints. Contact your HealtheIntent engagement leader if you need authorization granted.

Endpoint System Account Authorization Required
/feeds Must be authorized for feed administration
/feeds/{feedId} Must be authorized to access the specified feed
/feeds/{feedId}/bundles Must be authorized to access the specified feed
/bundles/{bundleId} Must be authorized to access the feed to which the specified bundle belongs
/channels Must be authorized for channel administration
/channels/{channelId} Must be authorized to access the specified channel
/channels/{channelId}/deliveries Must be authorized to access the specified channel
/deliveries/{deliveryId} Must be authorized to access the channel to which the specified delivery belongs
/downloads/{deliveryId} Must be authorized to access the channel to which the specified delivery belongs

Requesting a Feed and Channel

Before you can use the Data Syndication API, you must have at least one feed and at least one channel for that feed. Contact your HealtheIntent engagement leader to request that these be set up.

Looking Up Feeds and Deliveries

You can use the /feeds/{feedId}/bundles endpoint to view all the bundles that have been produced for a given feed or the /channels/{channelId}/deliveries endpoint to see all the deliveries that have occurred for a given channel.

Downloading the Latest Deliveries

Example Automated Downloading Script

require 'fileutils'
require 'httparty'

# Replace cernerdemo with your tenant mnemonic.
BASE_URL = 'https://cernerdemo.api.healtheintent.com/data-syndication/v1'
# Replace this with the ID of the channel for your feed.
CHANNEL_ID = '5fcdb1e1-3b82-4272-acfb-1242d456e4f4'
# Insert a valid Authorization header here.
AUTH_HEADER = '...'
# This script divides each download into parts. This constant sets the maximum number of bytes in each part.
PART_SIZE = 1024 * 1024 * 600

def download_new_deliveries
  loop do
    # Get the timestamp of the last downloaded bundle from persistence.
    last_released_at = File.read('checkpoint.txt') if File.exist?('checkpoint.txt')

    query_params = { orderBy: 'bundleReleasedAt', offset: 0, limit: 1 }
    query_params.merge!(bundleReleasedAfter: last_released_at) unless last_released_at.nil?

    headers = { 'Authorization' => AUTH_HEADER, 'Accept' => 'application/json' }
    url = "#{BASE_URL}/channels/#{CHANNEL_ID}/deliveries"
    response = HTTParty.get(url, headers: headers, query: query_params)
    unless response.code == 200
      raise StandardError, "Unable to retrieve latest deliveries. Response code = #{response.code}. Response body:\n#{response.body}"
    end

    delivery = response.parsed_response['items'].first

    if delivery.nil?
      puts 'No more bundles are available for download at this time.'
      break
    end

    if delivery['status'] == 'IN_PROGRESS'
      puts 'The download for the next bundle is still being prepared. Try again later.'
      break
    end

    if delivery['status'] != 'DELIVERED'
      raise StandardError, "The delivery with ID #{delivery['id']} failed. Contact your HealtheIntent engagement leader for support."
    end

    released_at = delivery['bundle']['releasedAt']
    filename = "#{released_at.delete('-:.')}#{get_file_extension(delivery['metadata']['archiveFormat'])}"
    puts "Downloading bundle released at #{released_at}."
    download_file(delivery['id'], filename)

    File.write('checkpoint.txt', delivery['bundle']['releasedAt'])
  end
end

def get_file_extension(archiveFormat)
  if archiveFormat == 'TAR_GZ'
    '.tar.gz'
  elsif archiveFormat == 'TAR_CONTAINING_LZ4'
    '.tar'
  end
end

def get_download_size(id)
  headers = {
    'Authorization' => AUTH_HEADER,
    'Accept' => 'application/octet-stream'
  }

  url = "#{BASE_URL}/downloads/#{id}"
  response = HTTParty.head(url, headers: headers)
  content_length = response.headers['Content-Length']
  unless response.code == 200 && content_length
    raise StandardError, "Unable to retrieve file size. Response code = #{response.code}. Response headers:\n#{response.headers}\nResponse body:\n#{response.body}"
  end

  content_length.to_i
end

def download_range(id, range, part_filename, retries = 3)
  headers = {
    'Authorization' => AUTH_HEADER,
    'Accept' => 'application/octet-stream',
    'Range' => "bytes=#{range}"
  }

  url = "#{BASE_URL}/downloads/#{id}"
  response = HTTParty.get(url, headers: headers)
  if response.code != 206
    raise StandardError, "Unexpected response code when attempting to download range. Response code = #{response.code}. Response body:\n#{response.body}"
  end

  File.binwrite(part_filename, response.body)
rescue StandardError => ex
  puts "Error: #{ex}"
  if retries > 0
    puts 'Retrying...'
    sleep 5
    download_range(id, range, part_filename, retries - 1)
  else
    raise StandardError, 'Unable to download range. Try again later.'
  end
end

def download_file(id, filename)
  length = get_download_size(id)
  puts "File size: #{length} bytes"

  dir = "#{filename}.parts"
  FileUtils.mkdir_p(dir)

  range_start = 0
  part_filenames = []

  while range_start < length
    range_end = [range_start + PART_SIZE, length].min - 1
    range = "#{range_start}-#{range_end}"
    part_filename = File.join(dir, "#{range_start}-#{range_end}")
    part_filenames << part_filename

    if File.exist?(part_filename) && File.size(part_filename) == (range_end - range_start + 1)
      puts "Already downloaded range #{range}."
    else
      puts "Downloading range #{range}."
      download_range(id, range, part_filename)
    end

    range_start += PART_SIZE
  end

  puts "All ranges downloaded. Combining ranges into final file: #{filename}"
  file = File.open(filename, 'wb')
  part_filenames.each do |part_filename|
    part_file = File.open(part_filename, 'rb')
    FileUtils.copy_stream(part_file, file)
    part_file.close
  end
  file.close

  # Delete the temporary files containing the separate parts.
  FileUtils.rm_r(dir)
end

download_new_deliveries

If you have a channel that uses the DOWNLOAD channel type, then you likely want to set up an automated process that regularly scans for new deliveries and downloads them. Complete the following steps to automatically download the delivered bundles:

  1. Determine your channel ID. You can use the /feeds endpoint to determine the feed ID, then use the /channels endpoint to determine the channel with that feed ID and a channel type mnemonic of DOWNLOAD.
  2. Use the /channels/{channelId}/deliveries endpoint to determine the list of available deliveries.
    • You will use the delivery’s id in the next step to perform the download.
    • Look for deliveries whose status field is DELIVERED, indicating they are available to download now.
    • Each delivery includes a bundle.releasedAt field that indicates the date and time when the bundle was produced. You can order and filter the response by specifying the bundleReleasedAt and bundleReleasedAfter query parameters. You can use those parameters to download all the deliveries up to a certain date and time, then save the bundle.releasedAt value so you can use the value in the bundleReleasedAfter query parameter next time and download only the new deliveries.
  3. Use the /downloads/{deliveryId} endpoint to download the data.
    • The format of the downloaded file is determined by the channel configuration’s archiveFormat attribute. If it is not set or is set to TAR_GZ, the file is a gzip-compressed tar archive file and should have a file extension of .tar.gz. If it is set to TAR_CONTAINING_LZ4, the downloaded file is a tar archive containing LZ4-compressed files and should have a file extension of .tar. While a .tar.gz file can be extracted and decompressed all at once, the .tar first needs to be extracted then the files within it can be decompressed using LZ4. The archive format used for a delivery also is included in the delivery’s metadata as the archiveFormat attribute. Note that a channel’s configuration can be updated to change the format of future deliveries. The format in a delivery’s metadata should be used when determining how to handle the file, since that reflects the actual format of the file.

The example automated downloading script demonstrates how to download all the deliveries of a given channel in order. The script can be run automatically on a schedule to ensure that you retrieve new deliveries as they become available. You will likely want to include the following features of the script in your code:

Feeds

Retrieve a List of Feeds

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/feeds?feedTypeMnemonic=long-record&orderBy=name',
  headers: {
    'Accept' => 'application/json',
    'Authorization' => '<auth_header>'
  }
)
curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/feeds?feedTypeMnemonic=long-record&orderBy=name'

Example Response

{
  "items": [
    {
      "id": "0f1c7802-6255-46f0-b898-6e5b851bc0af",
      "name": "Primary Population Records",
      "status": "ACTIVE",
      "scope": {
        "population": {
          "id": "5bdb91f7-c779-450d-8309-e14cd7672589"
        }
      },
      "feedType": {
        "mnemonic": "long-record"
      },
      "createdAt": "2018-04-06T21:17:55.423Z",
      "updatedAt": "2018-04-06T21:17:55.423Z"
    }
  ],
  "totalResults": 1,
  "firstLink": "https://cernerdemo.api.devhealtheintent.com/data-syndication/v1/feeds?feedTypeMnemonic=long-record&orderBy=name&offset=0&limit=20",
  "lastLink": "https://cernerdemo.api.devhealtheintent.com/data-syndication/v1/feeds?feedTypeMnemonic=long-record&orderBy=name&offset=0&limit=20&",
}

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/feeds

Retrieves a list of feeds matching the query.

Query Parameters

Parameter Default Required Description Accepted Values
feedTypeMnemonic N/A No Filters results to the given type of feed.
status N/A No Filters results by feed status. ACTIVE, INACTIVE
orderBy name No Orders results by a given value in ascending or descending alphabetic order. To specify descending, prefix the value with a hyphen (-). name, -name
offset 0 No 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 20 No The maximum number of results to display per page. The minimum limit is 1. The maximum limit is 100.

Responses

Status Type Description
200 Feed List Response Collection of Feed objects
400 Error Bad request
401 Error Unauthorized
403 Error Forbidden

Retrieve a Single Feed

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/feeds/0f1c7802-6255-46f0-b898-6e5b851bc0af',
  headers: {
    'Accept' => 'application/json',
    'Authorization' => '<auth_header>'
  }
)
curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/feeds/0f1c7802-6255-46f0-b898-6e5b851bc0af'

Example Response

{
  "id": "0f1c7802-6255-46f0-b898-6e5b851bc0af",
  "name": "Primary Population Records",
  "status": "ACTIVE",
  "scope": {
    "population": {
      "id": "5bdb91f7-c779-450d-8309-e14cd7672589"
    }
  },
  "feedType": {
    "mnemonic": "long-record"
  },
  "createdAt": "2018-04-06T21:17:55.423Z",
  "updatedAt": "2018-04-06T21:17:55.423Z"
}

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/feeds/{feedId}

Retrieves a single feed.

Path Parameters

Field Description
feedId The ID of the feed

Responses

Status Type Description
200 Feed Single Feed object
400 Error Bad request
401 Error Unauthorized
403 Error Forbidden
404 Error Not found

Bundles

Retrieve a List of Bundles

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/feeds/0f1c7802-6255-46f0-b898-6e5b851bc0af/bundles?releasedAfter=2018-02-03T01:00:00.000Z&orderBy=releasedAt',
  headers: {
    'Accept' => 'application/json',
    'Authorization' => '<auth_header>'
  }
)
curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/feeds/0f1c7802-6255-46f0-b898-6e5b851bc0af/bundles?releasedAfter=2018-02-03T01:00:00.000Z&orderBy=releasedAt'

Example Response

{
  "items": [
    {
      "id": "5ebcac9e-1f1a-4181-8c0f-4300a3af83d9",
      "feed": {
        "id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"
      },
      "releasedAt": "2018-04-11T18:37:25.063Z",
      "metadata": {}
    },
    {
      "id": "8d75de0e-358b-434d-97fe-6f1ba3598098",
      "feed": {
        "id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"
      },
      "releasedAt": "2018-04-11T20:21:12.461Z",
      "metadata": {}
    }
  ],
  "totalResults": 2,
  "firstLink": "https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/feeds/0f1c7802-6255-46f0-b898-6e5b851bc0af/bundles?releasedAfter=2018-02-03T01:00:00.000Z&orderBy=releasedAt&offset=0&limit=20",
  "lastLink": "https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/feeds/0f1c7802-6255-46f0-b898-6e5b851bc0af/bundles?releasedAfter=2018-02-03T01:00:00.000Z&orderBy=releasedAt&offset=0&limit=20",
}

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/feeds/{feedId}/bundles

Retrieves a list of bundles matching the query.

Path Parameters

Field Description
feedId The ID of the feed

Query Parameters

Parameter Default Required Description Accepted Values
releasedAfter N/A No If provided, only bundles released after the provided date and time are returned. The expected format is YYYY-MM-DDThh:mm:ssZ with optional milliseconds.
orderBy -releasedAt No Orders results by a given value in ascending or descending alphabetic order. To specify descending, prefix the value with a hyphen (-). releasedAt, -releasedAt
offset 0 No 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 20 No The maximum number of results to display per page. The minimum limit is 1. The maximum limit is 100.

Responses

Status Type Description
200 Bundle List Response Collection of Bundle objects
400 Error Bad request
401 Error Unauthorized
403 Error Forbidden

Retrieve a Single Bundle

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/bundles/5ebcac9e-1f1a-4181-8c0f-4300a3af83d9',
  headers: {
    'Accept' => 'application/json',
    'Authorization' => '<auth_header>'
  }
)
curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/bundles/5ebcac9e-1f1a-4181-8c0f-4300a3af83d9'

Example Response

{
  "id": "5ebcac9e-1f1a-4181-8c0f-4300a3af83d9",
  "feed": {
    "id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"
  },
  "releasedAt": "2018-04-11T18:37:25.063Z",
  "metadata": {}
}

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/bundles/{bundleId}

Retrieves a single bundle.

Path Parameters

Field Description
bundleId The ID of the bundle

Responses

Status Type Description
200 Bundle Single Bundle object
400 Error Bad request
401 Error Unauthorized
403 Error Forbidden
404 Error Not found

Channels

Retrieve a List of Channels

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/channels?feedId=0f1c7802-6255-46f0-b898-6e5b851bc0af&orderBy=name',
  headers: {
    'Accept' => 'application/json',
    'Authorization' => '<auth_header>'
  }
)
curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/channels?feedId=0f1c7802-6255-46f0-b898-6e5b851bc0af&orderBy=name'

Example Response

{
  "items": [
    {
      "id": "5fcdb1e1-3b82-4272-acfb-1242d456e4f4",
      "name": "Download Primary Population Records",
      "feed": {
        "id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"
      },
      "type": "DOWNLOAD",
      "config": {
        "archiveFormat": "TAR_GZ"
      },
      "status": "ACTIVE",
      "createdAt": "2018-04-11T17:02:40.936Z",
      "updatedAt": "2018-04-11T17:02:40.936Z"
    }
  ],
  "totalResults": 1,
  "firstLink": "https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/channels?feedId=0f1c7802-6255-46f0-b898-6e5b851bc0af&orderBy=name&offset=0&limit=20",
  "lastLink": "https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/channels?feedId=0f1c7802-6255-46f0-b898-6e5b851bc0af&orderBy=name&offset=0&limit=20&"
}

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/channels

Retrieves a list of channels matching the query.

Query Parameters

Parameter Default Required Description Accepted Values
feedId N/A No Filters results to the given feed.
type N/A No Filters results to the given channel type. DOWNLOAD, S3
orderBy name No Orders results by a given value in ascending or descending alphabetic order. To specify descending, prefix the value with a hyphen (-). name, -name
offset 0 No 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 20 No The maximum number of results to display per page. The minimum limit is 1. The maximum limit is 100.

Responses

Status Type Description
200 Channel List Response Collection of Channel objects
400 Error Bad request
401 Error Unauthorized
403 Error Forbidden

Retrieve a Single Channel

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4',
  headers: {
    'Accept' => 'application/json',
    'Authorization' => '<auth_header>'
  }
)
curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4'

Example Response

{
  "id": "5fcdb1e1-3b82-4272-acfb-1242d456e4f4",
  "name": "Download Primary Population Records",
  "feed": {
    "id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"
  },
  "type": "DOWNLOAD",
  "config": {
    "archiveFormat": "TAR_GZ"
  },
  "status": "ACTIVE",
  "createdAt": "2018-04-11T17:02:40.936Z",
  "updatedAt": "2018-04-11T17:02:40.936Z"
}

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/channels/{channelId}

Retrieves a single channel.

Path Parameters

Field Description
channelId The ID of the channel

Responses

Status Type Description
200 Channel Single Channel object
400 Error Bad request
401 Error Unauthorized
403 Error Forbidden
404 Error Not found

Deliveries

Retrieve a List of Deliveries

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/deliveries?bundleReleasedAfter=2018-02-03T01:00:00.000Z&orderBy=bundleReleasedAt',
  headers: {
    'Accept' => 'application/json',
    'Authorization' => '<auth_header>'
  }
)
curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/deliveries?bundleReleasedAfter=2018-02-03T01:00:00.000Z&orderBy=bundleReleasedAt'

Example Response

{
  "items": [
    {
      "id": "5e8af1e6-1cdf-45f6-9d9a-3c314beac597",
      "bundle": {
        "id": "5ebcac9e-1f1a-4181-8c0f-4300a3af83d9",
        "releasedAt": "2018-04-11T18:37:25.063Z"
      },
      "channel": {
        "id": "5fcdb1e1-3b82-4272-acfb-1242d456e4f4"
      },
      "status": "DELIVERED",
      "deliveredAt": "2018-04-12T16:02:01.333Z",
      "metadata": {
        "bytesSize": 1073741824,
        "archiveFormat": "TAR_GZ"
      }
    },
    {
      "id": "f9647569-aa13-42c2-81ad-a20b46be775c",
      "bundle": {
        "id": "8d75de0e-358b-434d-97fe-6f1ba3598098",
        "releasedAt": "2018-04-11T20:21:12.461Z"
      },
      "channel": {
        "id": "5fcdb1e1-3b82-4272-acfb-1242d456e4f4"
      },
      "status": "IN_PROGRESS"
    }
  ],
  "totalResults": 2,
  "firstLink": "https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/deliveries?bundleReleasedAfter=2018-02-03T01:00:00.000Z&orderBy=bundleReleasedAt&offset=0&limit=20",
  "lastLink": "https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/deliveries?bundleReleasedAfter=2018-02-03T01:00:00.000Z&orderBy=bundleReleasedAt&offset=0&limit=20"
}

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/channels/{channelId}/deliveries

Retrieves a list of deliveries matching the query.

If the channel corresponds to the DOWNLOAD channel type, this endpoint can be used to list available deliveries that you have not yet downloaded and processed into your application. If you store the releasedAt time of the last delivery that was downloaded, it can be used as the bundleReleasedAfter query parameter of this endpoint to list deliveries after this last downloaded bundle in time sequence order.

Note: The feed type for your channel may have certain processing order requirements that must be followed by API consumers to maintain data integrity. For example, feed types that produce bundles with incremental changes might require processing to strictly follow bundleReleasedAt order as new bundles may depend on previous bundles. See the documentation for your particular feed type for details.

Path Parameters

Field Description
channelId The ID of the channel

Query Parameters

Parameter Default Required Description Accepted Values
bundleReleasedAfter N/A No If provided, only deliveries for bundles released after the provided date and time are returned. The expected format is YYYY-MM-DDThh:mm:ssZ with optional milliseconds.
orderBy -bundleReleasedAt No Orders results by a given value in ascending or descending alphabetic order. To specify descending, prefix the value with a hyphen (-). bundleReleasedAt, -bundleReleasedAt
offset 0 No 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 20 No The maximum number of results to display per page. The minimum limit is 1. The maximum limit is 100.

Responses

Status Type Description
200 Delivery List Response Collection of Delivery objects
400 Error Bad request
401 Error Unauthorized
403 Error Forbidden

Retrieve a Single Delivery

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/deliveries/5e8af1e6-1cdf-45f6-9d9a-3c314beac597',
  headers: {
    'Accept' => 'application/json',
    'Authorization' => '<auth_header>'
  }
)
curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/deliveries/5e8af1e6-1cdf-45f6-9d9a-3c314beac597'

Example Response

{
  "id": "5e8af1e6-1cdf-45f6-9d9a-3c314beac597",
  "bundle": {
    "id": "5ebcac9e-1f1a-4181-8c0f-4300a3af83d9",
    "releasedAt": "2018-04-11T18:37:25.063Z"
  },
  "channel": {
    "id": "5fcdb1e1-3b82-4272-acfb-1242d456e4f4"
  },
  "status": "DELIVERED",
  "deliveredAt": "2018-04-12T16:02:01.333Z",
  "metadata": {
    "bytesSize": 1073741824,
    "archiveFormat": "TAR_GZ"
  }
}

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/deliveries/{deliveryId}

Retrieves a single delivery.

Path Parameters

Field Description
deliveryId The ID of the delivery

Responses

Status Type Description
200 Delivery Single Delivery object
400 Error Bad request
401 Error Unauthorized
403 Error Forbidden
404 Error Not found

Downloads

If you have a channel whose channel type mnemonic is DOWNLOAD, then each delivery in that channel with a DELIVERED status is available for download. Use the Deliveries endpoint to find what downloads are available to you; use this endpoint to download the content.

Note: Downloads are available for only three weeks. See the Data Retention section for more information.

Retrieve a Single Download

Example Request

require 'httparty'

response = HTTParty.get(
  'https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/downloads/5e8af1e6-1cdf-45f6-9d9a-3c314beac597',
  headers: {
    'Authorization' => '<auth_header>',
    'Accept' => 'application/octet-stream',
    'Range' => 'bytes=0-104857599'
  }
)


File.binwrite('bundle.tar.gz', response.body)
curl -X GET -H 'Authorization: {auth_header}' -H 'Range: bytes=0-104857599'
'https://cernerdemo.api.us.healtheintent.com/data-syndication/v1/downloads/5e8af1e6-1cdf-45f6-9d9a-3c314beac597' > bundle.tar.gz

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/downloads/{deliveryId}

Retrieves the archive file containing the data from the bundle.

Note: To ensure no data was lost due to a failed connection, check that the downloaded file’s size is correct. If you requested a specific range using the Range header, check that the size matches what you requested. Otherwise, check that the size matches the Content-Length response header.

Path Parameters

Field Description
deliveryId The ID of the delivery

Range Header

If a file download times out due to its size, you may optionally include a Range header to indicate that you only want to download a portion of the file. After downloading all portions of the file, you can concatenate the portions and decompress the combined file.

You can also use the Range header in order to download multiple segments of the file in parallel. To do this, you would start multiple threads or processes, each of which makes a request for a different byte range, then concatenate the portions after they have all been downloaded. There are diminishing returns for increasing the number of concurrent requests; we suggest downloading files in segments of about 600MB and retrieving 5-10 segments at a time.

For more information about byte ranges, see Byte Ranges on the RFC 7233 page on the Internet Engineering Task Force (IETF) website.

The range header should take one of the following forms:

Although RFC 7233 defines a way to specify multiple ranges in a single request, the downloads endpoint does not currently support this.

See the download example request for an example of this header being set.

Data Syndication API Definitions

Bundle

Name Type Required Description
id string Yes The unique identifier of the bundle.
feed Feed Reference Yes The feed the bundle belongs to.
releasedAt dateTime Yes The date and time when the bundle was produced, in International Organization for Standardization (ISO) 8601 YYYY-MM-DDThh:mm:ss.SSSZ format. This field implies the ordering of bundles in a feed.
metadata object Yes The metadata related to the bundle. The schema of this object varies and is determined by the feed type of the feed the bundle belongs to.

Bundle List Response

Name Type Required Description
items [Bundle] Yes The list of bundles.
totalResults integer Yes The total number of results for the query.
prevLink string No The previous page of results. Absent on the first page of results.
nextLink string No The next page of results. Absent on the last page of results.
firstLink string Yes The first page of results.
lastLink string Yes The last page of results.

Bundle Reference

Name Type Required Description
id string Yes The unique identifier of the bundle.
releasedAt dateTime Yes The date and time when the bundle was released, in ISO 8601 YYYY-MM-DDThh:mm:ss.SSSZ format.

Channel

Name Type Required Description
id string Yes The unique identifier of the channel.
name string Yes The human-readable name for the channel.
type string Yes The channel type of which the channel is an instance. Possible values:
  • DOWNLOAD
  • S3
feed Feed Reference Yes The feed the channel delivers.
status string Yes The lifecycle status of the channel. Possible values:
  • PENDING - the channel is awaiting validation by Cerner
  • ACTIVE - the channel is active and can deliver bundles for its associated feed
  • INACTIVE - the delivery of bundles through this channel is stopped
Additional status values may be added in the future. To allow for future additions, consuming systems must gracefully handle unknown or undocumented status values. Any unknown or undocumented status value can safely be treated as not ACTIVE by consuming systems.
config Channel Configuration Yes The configuration of the channel.
createdAt dateTime Yes The date and time when the channel was created, in ISO 8601 YYYY-MM-DDThh:mm:ss.SSSZ format.
updatedAt dateTime Yes The date and time when the channel was last updated, in ISO 8601 YYYY-MM-DDThh:mm:ss.SSSZ format.

Channel Configuration

The schema of this configuration object varies depending on the channel type. Each channel type can have a different set of configuration options.

Download Channel Type Configuration

Name Type Required Description
archiveFormat string No The format of the files that are downloaded through the channel. The default format is TAR_GZ.

S3 Channel Type Configuration

Name Type Required Description
bucketName string Yes The name of the Amazon S3 bucket to which the channel delivers.
baseBucketPath string No The path in the bucket to which the channel delivers. The default is the bucket’s root path.
region string Yes The region of the bucket to which the channel delivers.
roleArn string Yes The Amazon Resource Name (ARN) for the Identity and Access Management (IAM) role that delivers the files to the specified bucket.

Channel List Response

Name Type Required Description
items [Channel] Yes The list of channels.
totalResults integer Yes The total number of results for the query.
prevLink string No The previous page of results. Absent on the first page of results.
nextLink string No The next page of results. Absent on the last page of results.
firstLink string Yes The first page of results.
lastLink string Yes The last page of results.

Channel Reference

Name Type Required Description
id string Yes The unique identifier of the channel.

Delivery

Name Type Required Description
id string Yes The unique identifier of the delivery.
bundle Bundle Reference Yes The bundle for the delivery.
channel Channel Reference Yes The channel the delivery belongs to.
deliveredAt dateTime No The date and time when the delivery was completed (was delivered for failed), in ISO 8601 YYYY-MM-DDThh:mm:ss.SSSZ format.
status string Yes The lifecycle status of the delivery. Possible values:
  • IN_PROGRESS - The delivery is in progress.
  • DELIVERED - The delivery was successful.
  • FAILED - The delivery failed.
  • PURGE_IN_PROGRESS - The archive file is in the process of being deleted and is no longer available for download (only applicable to the DOWNLOAD channel type).
  • PURGED - The archive has been deleted and is no longer available for download (only applicable to the DOWNLOAD channel type).
Additional status values may be added in the future. To allow for future additions, consuming systems must gracefully handle unknown or undocumented status values. Any unknown or undocumented status value can safely be treated as not DELIVERED by consuming systems.
purgedAt dateTime No The date and time when the delivery moved to PURGED status, in ISO 8601 YYYY-MM-DDThh:mm:ss.SSSZ format.
metadata object No The metadata related to the delivery. The schema of this object varies and is determined by the type of the channel this delivery belongs to.

Delivery List Response

Name Type Required Description
items [Delivery] Yes The list of deliveries.
totalResults integer Yes The total number of results for the query.
prevLink string No The previous page of results. Absent on the first page of results.
nextLink string No The next page of results. Absent on the last page of results.
firstLink string Yes The first page of results.
lastLink string Yes The last page of results.

Error

Name Type Required Description
code integer Yes The HTTP status code representing the error.
errorDetails [ErrorDetail] No A list of additional error details.
message string Yes A human-readable description of the error.

ErrorDetail

Name Type Required Description
domain string No A subsystem or context where an error occurred.
location string No The name of the field that caused an error.
locationType string No The location or type of the field that caused an error. Possible values: body, formData, header, path, query
message string No A human-readable description of the error.
reason string No A codified value representing the specific error resulting in the current error status.

Feed

Name Type Required Description
id string Yes The unique identifier of the feed.
name string Yes A human-readable name for the feed.
feedType Feed Type Reference Yes The feed type of which the feed is an instance.
scope Scope Yes The domain of the data contained in bundles produced by the feed (for example, for bundles whose data is population-wide, this contains the population ID). Which fields are present in the scope object vary depending on the feed type.
status string Yes The lifecycle status of the feed. Possible values:
  • ACTIVE - the feed is active and will produce bundles
  • INACTIVE - production of new bundles for the feed is stopped
Additional status values may be added in the future. To allow for future additions, consuming systems must gracefully handle unknown or undocumented status values. Any unknown or undocumented status value can safely be treated as not ACTIVE by consuming systems.
createdAt dateTime Yes The date and time when the feed was created, in ISO 8601 YYYY-MM-DDThh:mm:ss.SSSZ format.
updatedAt dateTime Yes The date and time when the feed was last updated, in ISO 8601 YYYY-MM-DDThh:mm:ss.SSSZ format.

Feed List Response

Name Type Required Description
items [Feed] Yes The list of feeds.
totalResults integer Yes The total number of results for the query.
prevLink string No The previous page of results. Absent on the first page of results.
nextLink string No The next page of results. Absent on the last page of results.
firstLink string Yes The first page of results.
lastLink string Yes The last page of results.

Feed Reference

Name Type Required Description
id string Yes The unique identifier of the feed.

Feed Type Reference

Name Type Required Description
mnemonic string Yes The mnemonic identifier of the feed type.

Scope

Name Type Required Description
population Scope Part No A scope part representing a population within the HealtheIntent platform.

Scope Part

Name Type Required Description
id string Yes The unique resource identifier for the scope part.
name string No A human-readable name for display purposes.