NAV Navbar
Logo cerner
Ruby Shell

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.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.healtheintent.com/cohort/v1/algorithms', headers: headers)

print JSON.pretty_generate(result)



# You can also use wget
curl -X GET https://cernerdemo.api.us.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.healtheintent.com/cohort/v1/algorithms?offset=0&limit=20",
  "lastLink": "https://cernerdemo.api.us.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.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.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.healtheintent.com/cohort/v1/cohorts', headers: headers)

print JSON.pretty_generate(result)



# You can also use wget
curl -X GET https://cernerdemo.api.us.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.healtheintent.com/cohort/v1/cohorts?offset=0&limit=20",
  "lastLink": "https://cernerdemo.api.us.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. -
Ruby Shell