Cohort API v1
A cohort is a subset of patients in a population. A cohort typically consists of patients with common clinical or demographic characteristics, for example, diabetic patients or patients enrolled in a specific Medicaid benefit plan. However, cohorts can be used for any purpose that requires a predefined subset of patients in a population. The patients who are included in a cohort are determined by versioned algorithms.
Note: The data retrieved by this API is not filtered based on sensitive data filters for HealtheIntent. Ensure that your implementations of this API are designed with this in mind. See Understand Sensitive Data in HealtheIntent in the Reference Pages on Cerner Wiki for more information.
URL: https://cernerdemo.api.us-1.healtheintent.com/cohort/v1
Algorithms
Cohort algorithms define the criteria a patient must meet to be included in a given cohort. For example, an algorithm might include patients with a certain diagnosis and benefit plan. The key parameters for some algorithms can be modified, which allows the algorithms to be tailored to each individual use.
Currently, Cerner defines and manages the list of available algorithms, but eventually this service will enable defining algorithms managed by the tenant. To request the creation of a new algorithm, contact your Cerner consultant.
Retrieve a List of Algorithms
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/cohort/v1/algorithms', headers: headers)
print JSON.pretty_generate(result)
# You can also use wget
curl -X GET https://cernerdemo.api.us-1.healtheintent.com/cohort/v1/algorithms \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'
Example response
{
"items": [
{
"id": "ecb8026a-64f9-11e8-adc0-fa7ae01bbebc",
"name": "Cerner Standard 2017 Emergency Visit in Prior Two Measurement Periods Cohort",
"description": "This cohort includes all the people in the population who have an emergency visit during the current or prior two measurement periods.",
"version": "1.0.0"
}
],
"totalResults": 1,
"firstLink": "https://cernerdemo.api.us-1.healtheintent.com/cohort/v1/algorithms?offset=0&limit=20",
"lastLink": "https://cernerdemo.api.us-1.healtheintent.com/cohort/v1/algorithms?offset=0&limit=20"
}
GET /algorithms
Retrieves a paginated list of algorithms that are sorted by version.
Parameters
Parameter | In | Type | Required | Default | Description | Accepted Values |
---|---|---|---|---|---|---|
name | query | string | false | N/A | The algorithm name. This parameter is used to perform a case-insensitive match on the full name. | - |
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 | Algorithm |
400 | Bad Request | Bad Request | Error |
401 | Unauthorized | Unauthorized | Error |
403 | Forbidden | Forbidden | Error |
Algorithm Version
Cohort algorithms are versioned. Each version of an algorithm is immutable and once published does not change. A cohort configuration references a specific version of an algorithm and must be updated to reference a newer version.
Algorithms follow the Semantic Versioning 2.0.0 specification. See Semantic Versioning 2.0.0 on the Semantic Versioning website for more information.
Retrieve a Single Algorithm 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-1.healtheintent.com/cohort/v1/algorithms/227ee4f0-6508-11e8-adc0-fa7ae01bbebc/versions/1.1.0', headers: headers)
print JSON.pretty_generate(result)
# You can also use wget
curl -X GET https://cernerdemo.api.us-1.healtheintent.com/cohort/v1/algorithms/227ee4f0-6508-11e8-adc0-fa7ae01bbebc/versions/1.1.0 \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'
Example response
{
"name": "Cerner Standard 2017 Outpatient Visit in Current Measurement Period Cohort",
"description": "This cohort includes all the people in the population who have an outpatient visit during the current measurement period.",
"parameters": [
{
"key": "cs2017-outpatient-visit-current-measurement-period-cohort/cohort-end-date",
"valueType": "ISO_8601_STRING",
"name": "cohort-end-date",
"description": "The end date of the measurement period.",
"required": false
}
]
}
GET /algorithms/{algorithmId}/versions/{id}
Retrieves a single version of the algorithm.
Parameters
Parameter | In | Type | Required | Default | Description | Accepted Values |
---|---|---|---|---|---|---|
algorithmId | path | string | true | N/A | The unique ID of the algorithm. | - |
id | path | string | true | N/A | The version of the algorithm. | - |
Response Statuses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | AlgorithmVersion |
401 | Unauthorized | Unauthorized | Error |
403 | Forbidden | Forbidden | Error |
404 | Not Found | Not Found | Error |
Cohort
A cohort definition describes what the cohort is and to which population it applies.
Retrieve a List of Cohorts
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/cohort/v1/cohorts', headers: headers)
print JSON.pretty_generate(result)
# You can also use wget
curl -X GET https://cernerdemo.api.us-1.healtheintent.com/cohort/v1/cohorts \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'
Example response
{
"items": [
{
"id": "fda89fee-1ca3-4c3f-80b3-66624c128ea8",
"name": "Cerner Standard 2017 Emergency Visit in Prior Two Measurement Periods Cohort",
"description": "This cohort includes all the people in the population who have an emergency visit during the current or prior two measurement periods.",
"population": {
"id": "1424e81d-8cea-4d6b-b140-d6630b684a58"
}
}
],
"totalResults": 1,
"firstLink": "https://cernerdemo.api.us-1.healtheintent.com/cohort/v1/cohorts?offset=0&limit=20",
"lastLink": "https://cernerdemo.api.us-1.healtheintent.com/cohort/v1/cohorts?offset=0&limit=20"
}
GET /cohorts
Retrieves a paginated list of cohorts.
Parameters
Parameter | In | Type | Required | Default | Description | Accepted Values |
---|---|---|---|---|---|---|
name | query | string | false | N/A | The name of the cohort. | - |
populationId | query | string | false | N/A | The ID of the population from which the cohort is created. | - |
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 | Cohort |
400 | Bad Request | Bad Request | Error |
401 | Unauthorized | Unauthorized | Error |
403 | Forbidden | Forbidden | Error |
Schema Definitions
Algorithm
Name | Type | Required | Description | Accepted Values |
---|---|---|---|---|
id | string | true | The unique ID of the algorithm. | - |
name | string | true | The name of the algorithm. | - |
description | string | false | The description of the algorithm. | - |
version | string | true | The version of the algorithm. Algorithms are created and managed internally by Cerner. Each algorithm is immutable, and new versions are published when updates are made. | - |
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. | - |
AlgorithmVersion
Name | Type | Required | Description | Accepted Values |
---|---|---|---|---|
name | string | true | The name of the algorithm. | - |
description | string | false | The description of the algorithm. | - |
parameters | AlgorithmParameter | false | The parameters used to change the default behavior of the algorithm. | - |
AlgorithmParameter
Name | Type | Required | Description | Accepted Values |
---|---|---|---|---|
key | string | true | The unique key that identifies the parameter. | - |
valueType | string | true | The type of the parameter value. | - |
name | string | true | The name of the parameter. | - |
description | string | false | The description of the parameter. | - |
required | boolean | true | Indicates whether the parameter is required. | - |
Cohort
Name | Type | Required | Description | Accepted Values |
---|---|---|---|---|
id | string | true | The unique ID of the cohort. | - |
name | string | true | The name of the cohort. | - |
description | string | false | The description of the cohort. | - |
population | PopulationReference | true | The ID of the population on which the cohort is built. | - |
PopulationReference
Name | Type | Required | Description | Accepted Values |
---|---|---|---|---|
id | string | true | The unique ID of the population. | - |