NAV Navbar
Logo cerner
Ruby Shell

Classic Data Ingestion API v1

The Classic Data Ingestion (CLDI) service API allows data contributors to upload, or ingest, a file that contains a batch of data records into HealtheIntent. In the CLDI service, an ingested file is referred to as a contributed file. The CLDI service’s processing structurally normalizes the contributed file and transforms each data record into a HealtheIntent data model that can then be used by other HealtheIntent services, for example, the Longitudinal Record service. The CLDI API also enables finding a contributed file, viewing its metadata, and downloading it.

Note: The data retrieved by this API is not filtered based on your sensitive data filters for HealtheIntent. Ensure that your implementations of this API are designed with this in mind. See the Understand Sensitive Data in HealtheIntent Reference Page for more information.

URL: https://cernerdemo.api.us-1.healtheintent.com/classic-data-ingestion/v1

Contributed Files

The CLDI service represents ingested data files as contributed files. A contributed file includes the file size, created date, and metadata such as the data source, data set, specification version, and the file that identifies what the file represents.

Upload a Contributed File

Example Request:




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

headers = {
  'Authorization' => '<auth_header>',
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'CLDI-DataSetId' => {
  "type": "string"
},
  'CLDI-SpecVersionId' => {
  "type": "string"
},
  'CLDI-FileId' => {
  "type": "string"
},
  'CLDI-Release' => {
  "type": "string"
},
  'CLDI-OriginalFileName' => {
  "type": "string"
},
  'Cerner-Correlation-Id' => {
  "type": "string"
}
} 

result = HTTParty.post('https://cernerdemo.api.us-1.healtheintent.com/classic-data-ingestion/v1/data-sources/c5d5f79c-72b3-43c6-91ec-b8692700311c/contributed-files/upload', headers: headers)

print JSON.pretty_generate(result)




# You can also use wget
curl -X POST https://cernerdemo.api.us-1.healtheintent.com/classic-data-ingestion/v1/data-sources/c5d5f79c-72b3-43c6-91ec-b8692700311c/contributed-files/upload \
-H 'Authorization: {auth_header}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'CLDI-DataSetId: [object Object]' \
-H 'CLDI-SpecVersionId: [object Object]' \
-H 'CLDI-FileId: [object Object]' \
-H 'CLDI-Release: [object Object]' \
-H 'CLDI-OriginalFileName: [object Object]' \
-H 'Cerner-Correlation-Id: [object Object]'

Example response

{
  "contributedFile": {
    "id": "c5d5f79c-72b3-43c6-91ec-b8692700311c"
  }
}

POST /data-sources/{dataSourceId}/contributed-files/upload

Uploads a file to the CLDI service. The contributed file must be identified by the data source, data set, specification version, the file it represents, and the file’s release. The release is used to group related files together for CLDI processing, to order files for CLDI processing, and to identify whether an uploaded file is intended to replace a previously uploaded file. When two files are uploaded with the same ID and release, the most recently uploaded file takes precedence over the previous one. For example, assume a data contributor sends one file that contains claim header records and another that contains claim detail records. These two files must be processed together to transform the claim header and detail records into a HealtheIntent claim data model. To facilitate this, the CLDI service uses the release to group the files for processing. Generally, the release is the date (or date and time) when the file extract was produced.

Parameters

Parameter In Type Required Default Description Accepted Values
CLDI-DataSetId header string true N/A The ID of the data set to which the file pertains in the specified data source. -
CLDI-SpecVersionId header string true N/A The ID of the specification version to which the file conforms in the specified data set, for example, 1. -
CLDI-FileId header string true N/A The ID of the file that the file represents in the specification version, for example, FILE_1. -
CLDI-Release header string true N/A The release of the file that is uploaded. Cerner recommends that the release be in either yyyymmdd or yyyymmddhhmm format. -
CLDI-OriginalFileName header string false N/A The optional name used to identify the file that is uploaded. This is usually used to stamp the name of the file from the data contributor’s local file system. The file name must begin with and contain only alphanumeric characters, hyphens, underscores, and dot characters. The name must end with an alphanumeric character. -
Cerner-Correlation-Id header string false N/A An optional but strongly recommended ID that can be used to trace the request through services. This ID helps investigate issues. Typically, a randomly generated universally unique identifier (UUID) is used. -
dataSourceId path string true N/A The ID of the data source. -
body body postDataSourcesDatasourceidContributedFilesUpload true N/A No description -

Response Statuses

Status Meaning Description Schema
201 Created Created ContributedFile
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error

Retrieve a List of Contributed Files

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-1.healtheintent.com/classic-data-ingestion/v1/data-sources/c5d5f79c-72b3-43c6-91ec-b8692700311c/contributed-files', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X GET https://cernerdemo.api.us-1.healtheintent.com/classic-data-ingestion/v1/data-sources/c5d5f79c-72b3-43c6-91ec-b8692700311c/contributed-files \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

Example response

{
  "items": [
    {
      "dataSet": {
        "id": "c5d5f79c-72b3-43c6-91ec-b8692700311c"
      },
      "specVersion": {
        "id": "1"
      },
      "file": {
        "id": "FILE_1"
      },
      "release": "20180919",
      "fileSize": "123",
      "createdAt": "2018-09-20T11:32:57.041Z"
    }
  ],
  "totalResults": 1,
  "firstLink": "https://cernerdemo.api.us-1.healtheintent.com/example/v1/examples?offset=0&limit=20",
  "lastLink": "https://cernerdemo.api.us-1.healtheintent.com/example/v1/examples?offset=0&limit=20"
}

GET /data-sources/{dataSourceId}/contributed-files

Retrieves a list of contribute files for the given data source.

Parameters

Parameter In Type Required Default Description Accepted Values
dataSourceId path string true N/A The ID of the data source. -
dataSetId query string false N/A Filters the contributed files to those that the match the specified data set. -
specVersion query string false N/A Filter the contributed files to those that use the specified specification version. Specify this only if the dataSetId query parameter is provided, because the specVersion field is unique only in the parent data set. -
fileId query string false N/A Filters the contributed files to those that include the specified file. Specify this only if the specVersion query parameter is provided, because the fileId field is unique only in the parent specification version. -
release query string false N/A Filters the contributed files to only those that include the specified release. Partial matching is allowed, for example, 1999 can return 1999, 19990501, and 199905010830. -
orderBy query string false -createdAt,-release A comma-separated list of fields by which to sort. createdAt, -createdAt, release, -release, -createdAt,-release, -createdAt,release, createdAt,-release, createdAt,release
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 OK ContributedFiles
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error

Retrieve a Single Contributed File

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-1.healtheintent.com/classic-data-ingestion/v1/data-sources/c5d5f79c-72b3-43c6-91ec-b8692700311c/contributed-files/f134583d-59bb-4292-be45-3901f6cbaaab', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X GET https://cernerdemo.api.us-1.healtheintent.com/classic-data-ingestion/v1/data-sources/c5d5f79c-72b3-43c6-91ec-b8692700311c/contributed-files/f134583d-59bb-4292-be45-3901f6cbaaab \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

Example response

{
  "dataSet": {
    "id": "c5d5f79c-72b3-43c6-91ec-b8692700311c"
  },
  "specVersion": {
    "id": "1"
  },
  "file": {
    "id": "FILE_1"
  },
  "release": "20180919",
  "fileSize": "123",
  "createdAt": "2018-09-20T11:32:57.041Z"
}

GET /data-sources/{dataSourceId}/contributed-files/{contributedFileId}

Retrieves a single contributed record by its ID.

Parameters

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

Response Statuses

Status Meaning Description Schema
200 OK OK ContributedFile
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error

Download a Contributed File

Example Request:


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

headers = {
  'Authorization' => '<auth_header>',
  'Accept' => 'application/octet-stream',
  'Accept-Encoding' => {
  "type": "string"
},
  'Cerner-Correlation-Id' => {
  "type": "string"
}
} 

result = HTTParty.get('https://cernerdemo.api.us-1.healtheintent.com/classic-data-ingestion/v1/data-sources/c5d5f79c-72b3-43c6-91ec-b8692700311c/contributed-files/f134583d-59bb-4292-be45-3901f6cbaaab/download', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X GET https://cernerdemo.api.us-1.healtheintent.com/classic-data-ingestion/v1/data-sources/c5d5f79c-72b3-43c6-91ec-b8692700311c/contributed-files/f134583d-59bb-4292-be45-3901f6cbaaab/download \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/octet-stream' \
-H 'Accept-Encoding: [object Object]' \
-H 'Cerner-Correlation-Id: [object Object]'

GET /data-sources/{dataSourceId}/contributed-files/{contributedFileId}/download

Downloads the file contents of a contributed file.

Parameters

Parameter In Type Required Default Description Accepted Values
Accept-Encoding header string false N/A Optionally indicates the content encoding that is acceptable in the response. Currently, gzip is the only supported value. -
Cerner-Correlation-Id header string false N/A An optional but strongly recommended ID that can be used to trace the request through services. This ID helps investigate issues. Typically, a randomly generated UUID is used. -
dataSourceId path string true N/A The ID of the data source. -
contributedFileId path string true N/A The ID of the contributed file. -

Response Statuses

Status Meaning Description Schema
200 OK OK File
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error

Data Sources

Data sources are CLDI-specific buckets into which data contributors upload data files. Generally, a data source identifies a source system from which data is ingested; however, multiple data sources can receive data from the same source system. Each data source must have a name, and Cerner recommends that the name clearly differentiates the data source from others. Each data source is owned by a single tenant and cannot be shared directly with other tenants. A data source must be specified when a file is uploaded.

Add a Data Source

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-1.healtheintent.com/classic-data-ingestion/v1/data-sources', headers: headers)

print JSON.pretty_generate(result)




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

Example response

{
  "id": "c5d5f79c-72b3-43c6-91ec-b8692700311c",
  "name": "Cerner Demo",
  "description": "Cerner - Demo EMR",
  "tags": [
    {
      "key": "Use",
      "value": "Production"
    }
  ]
}

POST /data-sources

Creates a data source owned by the specified tenant in the CLDI service.

Parameters

Parameter In Type Required Default Description Accepted Values
body body postDataSources true N/A No description -

Response Statuses

Status Meaning Description Schema
201 Created Created DataSource
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error

Retrieve a List of 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-1.healtheintent.com/classic-data-ingestion/v1/data-sources', headers: headers)

print JSON.pretty_generate(result)


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

Example response

{
  "items": [
    {
      "id": "c5d5f79c-72b3-43c6-91ec-b8692700311c",
      "name": "Cerner Demo",
      "description": "Cerner - Demo EMR",
      "tags": [
        {
          "key": "Use",
          "value": "Production"
        }
      ]
    }
  ],
  "totalResults": 1,
  "firstLink": "https://cernerdemo.api.us-1.healtheintent.com/example/v1/examples?offset=0&limit=20",
  "lastLink": "https://cernerdemo.api.us-1.healtheintent.com/example/v1/examples?offset=0&limit=20"
}

GET /data-sources

Retrieves all the data sources owned by the specified tenant in the CLDI service.

Parameters

Parameter In Type Required Default Description Accepted Values
id query array[string] false N/A Filters the data sources to those with any of the specified IDs. A maximum of 20 IDs can be specified in a single request. -
name query string false N/A Filters the data sources to only those with the specified name. Case insensitive and partial string matching are supported, which means that any data source with a name that contains the specified characters regardless of case is returned. For example, a value of cross returns both Blue Cross Blue Shield and Rivercross Health EMR. -
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 OK DataSources
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error

Update a Data Source

Example Request:




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

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

result = HTTParty.patch('https://cernerdemo.api.us-1.healtheintent.com/classic-data-ingestion/v1/data-sources/c5d5f79c-72b3-43c6-91ec-b8692700311c', headers: headers)

print JSON.pretty_generate(result)




# You can also use wget
curl -X PATCH https://cernerdemo.api.us-1.healtheintent.com/classic-data-ingestion/v1/data-sources/c5d5f79c-72b3-43c6-91ec-b8692700311c \
-H 'Authorization: {auth_header}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'

PATCH /data-sources/{dataSourceId}

Updates the specified data source owned by the specified tenant in the CLDI service. A data source can be updated by only the tenant who owns it.

Parameters

Parameter In Type Required Default Description Accepted Values
dataSourceId path string true N/A The ID of the data source. -
body body patchDataSources 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

Retrieve a Single 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-1.healtheintent.com/classic-data-ingestion/v1/data-sources/c5d5f79c-72b3-43c6-91ec-b8692700311c', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X GET https://cernerdemo.api.us-1.healtheintent.com/classic-data-ingestion/v1/data-sources/c5d5f79c-72b3-43c6-91ec-b8692700311c \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

Example response

{
  "id": "c5d5f79c-72b3-43c6-91ec-b8692700311c",
  "name": "Cerner Demo",
  "description": "Cerner - Demo EMR",
  "tags": [
    {
      "key": "Use",
      "value": "Production"
    }
  ]
}

GET /data-sources/{dataSourceId}

Retrieves the specified data source owned by the specified tenant in the CLDI service. A data source can be retrieved by only the tenant who owns it.

Parameters

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

Response Statuses

Status Meaning Description Schema
200 OK OK DataSource
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error

Schema Definitions

Tag

Name Type Required Description Accepted Values
key string true The intended use of the tag. The key must be unique in a given resource. The maximum length is 128 Unicode characters, and the minimum is 1. -
value string false The optional, specific instance of the use of the tag. The maximum length is 256 Unicode characters, and the minimum is 0. -

postDataSources

Name Type Required Description Accepted Values
name string true The name of the data source. -
tags [Tag] false Tags allow owners to add metadata to a data source and can be used to indicate the meaning, purpose, or more precise ownership of the data source. Tags are optional but can be used to filter retrieved data sources and to organize data sources. The data source owner controls the use of tags. A tag consists of a key and an optional value. The key field indicates the intended use of the tag (for example Use to indicate how the data from the data source is intended to be used), and the optional value field indicates the specific instance of the intended use (for example, Production to indicate that the data is intended to be used in a production environment). -
description string false The description of the data source. A description can give more details about the source and the data contributed from it. -

DataSource

Name Type Required Description Accepted Values
id string false The ID of the data source that was specified when the file was uploaded. -
name string false The name of the data source. -
description string false The description of the data source. A description can give more details about the source and the data contributed from it. -
tags [Tag] false Tags allow owners to add metadata to a data source and can be used to indicate the meaning, purpose, or more precise ownership of the data source. Tags are optional but can be used to filter retrieved data sources and to organize data sources. The data source owner controls the use of tags. A tag consists of a key and an optional value. The key field indicates the intended use of the tag (for example Use to indicate how the data from the data source is intended to be used), and the optional value field indicates the specific instance of the intended use (for example, Production to indicate that the data is intended to be used in a production environment). -

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

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

patchDataSources

Name Type Required Description Accepted Values
name string false The name of the data source. -
description string false The description of the data source. A description can give more details about the source and the data contributed from it. -
tags [Tag] false Tags allow owners to add metadata to a data source and can be used to indicate the meaning, purpose, or more precise ownership of the data source. Tags are optional but can be used to filter retrieved data sources and to organize data sources. The data source owner controls the use of tags. A tag consists of a key and an optional value. The key field indicates the intended use of the tag (for example Use to indicate how the data from the data source is intended to be used), and the optional value field indicates the specific instance of the intended use (for example, Production to indicate that the data is intended to be used in a production environment). -

File

Name Type Required Description Accepted Values
id string true The ID of the file that the file represents in the specification version, for example, FILE_1. -

postDataSourcesDatasourceidContributedFilesUpload

Name Type Required Description Accepted Values
file File true The contributed file to upload. -

ContributedFile

Name Type Required Description Accepted Values
contributedFile ContributedFileReference false A reference to the contributed file, the ID of which was assigned by the Classic Data Ingestion service when the file was uploaded. -

ContributedFileReference

Name Type Required Description Accepted Values
id string false A reference to the contributed file, the ID of which was assigned by the Classic Data Ingestion service when the file was uploaded. -

ContributedFiles

Name Type Required Description Accepted Values
items [ContributedFile] 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. -