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.

For more information about the specifications of the extracted files, see the Data Syndication Data Sets.

Extraction History API

Use this API to retrieve a list of extracted files available for a given client or the details of a single file by ID. You can add start and end dates as query parameters on an extraction history request to retrieve a list of data extract files that were created during a specific time period. The response will contain the file ID, extract type, dataset type, release date, file size, and version number for each file. You can retrieve only metadata (dates, sizes, IDs, etc.) with this API — the data files themselves must be downloaded with the File Download API.

Extraction History Object

Example Extraction History object

{
  "id": 159,
  "population_id": "1424e81d-8cea-4d6b-b140-d6630b684a58",
  "extract_type": "INCREMENTAL",
  "dataset_type": "LONG_REC",
  "released_at": "2016-11-11T08:23:06Z",
  "size_in_bytes": 55004256,
  "version": "1.0.0"
}
Name Type Description
id integer An automatically incremented ID that is unique to the extracted data set
population_id string The population ID for the extracted data
extract_type string The extract type (COMPLETE or INCREMENTAL)
dataset_type string The type of data set that was extracted. For longitudinal records it is LONG_REC.
released_at string The date and time of the release of the data set (YYYY-MM-DDTHH:MM:SSZ)
size_in_bytes integer The extracted file size in bytes
version string The specification version of the extracted data ([major].[minor].[patch])

Get an Extraction History List

Example Request:

curl -H 'Authorization: auth_header' https://cernerdemo.datasyndication.healtheintent.com/api/extracts
require 'httparty'

HTTParty.get('https://cernerdemo.datasyndication.healtheintent.com/api/extracts',
  headers: { 'Authorization' => 'auth_header'}
)

Example Response:

[
  {
    "id": 1,
    "population_id": "17c7947e-0fc0-4db6-adaa-7dd15d7fb100",
    "extract_type": "INCREMENTAL",
    "dataset_type": "LONG_REC",
    "released_at": "2016-07-07T09:11:38Z",
    "size_in_bytes": 319249,
    "version": "1.0.0"
  },
  {
    "id": 2,
    "population_id": "17c7947e-0fc0-4db6-adaa-7dd15d7fb100",
    "extract_type": "INCREMENTAL",
    "dataset_type": "LONG_REC",
    "released_at": "2016-07-07T09:11:38Z",
    "size_in_bytes": 319249,
    "version": "1.0.0"
  }
]

GET https://{client}.datasyndication.healtheintent.com/api/extracts

Use this API to retrieve a list of extracted files available for a given client. You can add query parameters to an extraction history request to retrieve a list of data extract files filtered by type and extraction date.

URI Templates

Without Query Parameters

https://{client_mnemonic}.datasyndication.healtheintent.com/api/extracts

With Query Parameters

https://{client_mnemonic}.datasyndication.healtheintent.com/api/extracts?extract_type={extract_type}&start_date={start_date}&end_date={end_date}&start={start}&limit={limit}

Path Parameters

Parameter Description
client_mnemonic The mnemonic for the client

Query Parameters

Parameter Description
extract_type Must be COMPLETE or INCREMENTAL; limits the response qualified to the extract type specified
start_date Must be in YYYY-MM-DD or YYYY-MM-DDThh:mm:ssZ format; limits the response qualified to extraction begin date specified
end_date Must be in YYYY-MM-DD or YYYY-MM-DDThh:mm:ssZ format; limits the response qualified to extraction end date specified
limit The number of records to be qualified in the response starting from the record passed in the start parameter
start The Nth record where N equals the integer passed in this parameter

Get an Extraction History Object by ID

Example Request:

curl -H 'Authorization: auth_header' https://cernerdemo.datasyndication.healtheintent.com/api/extracts/1
require 'httparty'

HTTParty.get('https://cernerdemo.datasyndication.healtheintent.com/api/extracts/1',
  headers: { 'Authorization' => 'auth_header'}
)

Example Response:

{
  "id": 1,
  "population_id": "17c7947e-0fc0-4db6-adaa-7dd15d7fb100",
  "extract_type": "INCREMENTAL",
  "dataset_type": "LONG_REC",
  "released_at": "2016-07-07T09:11:38Z",
  "size_in_bytes": 319249,
  "version": "1.0.0"
}

GET https://{client_mnemonic}.datasyndication.healtheintent.com/api/extracts/{id}

Add an extract ID to the path to return the extract details for a single file.

URI Template

https://{client_mnemonic}.datasyndication.healtheintent.com/api/extracts/{id}

Path Parameters

Parameter Description
client_mnemonic The mnemonic for the client
id The unique extract ID of the file to be downloaded

Responses

Status Type Description
200 Extract Longitudinal Record Summary Object The Extract Longitudinal Record Summary JSON
400 Exception Bad Request
401 string Unauthorized
403 Exception Forbidden
404 Exception Not Found
500 Exception Internal Server Error

Extracted Longitudinal Record

Contents of TAR file

syndication_longrecord_I_cernerdemo_demopopulation_1.0.0_201610280625.tar.gz
  syndication_longrecord_I_cernerdemo_demopopulation_1.0.0_201610280625
    AdvanceDirective_RecorderIdentifier.txt
    AdvanceDirective.txt
    Allergy.txt
    Claim.txt
    Immunization.txt
    ...
    SummaryOfExtract.txt

This API allows you to download a specific data file or portions of a file. Downloaded files are delivered as compressed TAR files. The packaged TAR file contains pipe-delimited text files. Each text file contains a certain type of clinical or demographic information for the people in the population. The files are named using the formats below.

File Type Naming Format
Individual data sets {EntityName} or {SubEntityName}
Incremental extract files syndication_longrecord_I_{client_mnemonic}_{population_mnemonic}_{version}_{extract_date_and_time}.tar.gz
Complete extract files syndication_longrecord_C_{client_mnemonic}_{population_mnemonic}_{version}_{extract_date_and_time}.tar.gz

File identifier is a required parameter for all file download requests. Usually, you will need to call the Extraction History API first to get the file identifiers, and then use the identifiers in the file download requests to retrieve the actual data files.

Download an Extract

Example Request:

curl -H 'Authorization: auth_header' https://cernerdemo.datasyndication.healtheintent.com/api/extracts/1/download
require 'httparty'

HTTParty.get('https://cernerdemo.datasyndication.healtheintent.com/api/extracts/1/download',
  headers: { 'Authorization' => 'auth_header'}
)

GET https://cernerdemo.datasyndication.healtheintent.com/api/extracts/{id}/download

URI Template

https://{client_mnemonic}.datasyndication.healtheintent.com/api/extracts/{id}/download

Path Parameters

Parameter Description
client_mnemonic The mnemonic for the client
id The unique extract ID of the file to be downloaded

Download an Extract with Range Request

Example Request

curl -r [RANGE]- -H 'Authorization: auth_header' https://cernerdemo.datasyndication.healtheintent.com/api/extracts/1/download
require 'httparty'

HTTParty.get('https://cernerdemo.datasyndication.healtheintent.com/api/extracts/1/download',
  headers: { 'Authorization' => 'auth_header', 'Range' => 'bytes={start_point}-'}
)

If a file download times out due to its size, you can use HTTP byte ranges in the request header to download the file in smaller segments. Add byte ranges to your download request as follows:

  1. Note the byte at which the extract file stopped downloading.
  2. Enter the byte number noted in the previous step in the {Range} field of the request header as shown in the example request. {Range} is the byte at which the file download will begin. The request body is the same as when downloading an entire file.
  3. The system returns a 206 Partial Content status and the range of bytes that were successfully downloaded, for example, Status: 206 Partial Content Accept- Ranges: bytes Range: 0-98660352.
  4. Note the byte at which the partial extract file stopped downloading.
  5. Repeat Steps 2 through 4 until you have downloaded the whole file.
  6. Concatenate the partial files.
  7. Decompress the combined file.

Data Syndication API Definitions

Extracted Longitudinal Record Summary

Name Type Description
id integer An automatically incremented ID that is unique to the extracted data set
population_id string The Population ID for the extracted data
extract_type string Limits the response qualified to the extract type as specified (COMPLETE or INCREMENTAL)
dataset_type string The type of data set that is extracted as part of the syndication, for example for longitudinal records it is LONG_REC
released_at string The date and time of the release of the data set (YYYY-MM-DDTHH:MM:SSZ)
size_in_bytes integer The extracted file size in bytes
version string The specification version of the extracted data ([major].[minor].[patch])

Exception

Name Type Description
message string Descriptive message providing context for the error condition

Data Syndication Data Sets