NAV Navbar
Logo cerner
ruby shell

Readmission Risk API

Preventable readmissions are extremely costly to the health care industry. The Cerner readmission risk algorithm considers several risk factors to determine a person’s Readmission Risk Score representing the likelihood of readmission for the person.

Person

Person ID Lookup

Example Request

require 'httparty'

HTTParty.post(
  'https://cernerdemo.programs.healtheintent.com/api/populations/0a9cc467-094c-403a-84d0-35604e1e418c/data_partitions/8dee150d-505f-4635-b009-1bef63d7cf5a/persons',
  headers: {
    'Authorization' => '<auth_header>',
    'Content-Type' => 'application/json'
  },
  body: {values: ['3613400', '3705861']}.to_json
)
curl -X POST -H 'Authorization: <auth_header>' -H 'Content-Type: application/json' -d '{"values":["3613400","3705861"]}' https://cernerdemo.programs.healtheintent.com/api/populations/0a9cc467-094c-403a-84d0-35604e1e418c/data_partitions/8dee150d-505f-4635-b009-1bef63d7cf5a/persons

Example Response

{
  "empi_ids": [
    {
      "value": "3613400",
      "empi_id": "29ac4d44-3d7e-3e10-a60f-2127d27b107b",
      "status": "SUCCESS"
    },
    {
      "value": "3705861",
      "empi_id": "4ced02e8-ec49-3905-8032-5fb2d1105b02",
      "status": "SUCCESS"
    }
  ]
}

POST https://{client}.programs.healtheintent.com/api/populations/{population_id}/data_partitions/{data_partition_id}/persons

Because HealtheIntent collects data from many different sources, we use one identifier to consolidate their information. Readmission Risk Score endpoints require the person’s HealtheIntent ID which can be looked up from the person’s source (typically EMR) ID.

Path Parameters

Parameter Description
population_id The HealtheIntent population ID
data_partition_id The ID of the data partition the person belongs to

Request Message Body

A JSON array of local person IDs.

Parameter Type Description
values string The local ID corresponding to the Person

Responses

Status Type Description
200 PersonIDResponse The person ID response structure
406 ‘string’ No unique person was be found for the identifiers provided
400 ‘string’ Bad Request
401 ‘string’ Unauthorized
403 ‘string’ Forbidden
500 ‘string’ Internal Server Error

Readmission Risk Score

The Readmission Risk Score object contain a person’s risk score information and the factors used to calculate the score. APIs exist to retrieve current readmission risk scores for a single person or multiple people, as well as historical scores.

The Readmission Risk Score object

Example Readmission Risk Score object

 {
  "empi_id": "00e4fd48-efe7-301c-89bb-5f6d77312373",
  "normalized_risk_score": "39",
  "date": "2016-10-29T00:00:00.000Z",
  "stratification": "LOW",
  "risk_factors": [
    {
      "name": "age_in_years",
      "value": "32"
    },
    {
      "name": "insurance",
      "value": "MEDICAID"
    },
    {
      "name": "ama_history",
      "value": "0"
    },
    {
      "name": "er_in_last_six_months",
      "value": "false"
    },
    {
      "name": "inpatient_in_last_six_months",
      "value": "true"
    },
    {
      "name": "diuretics_current",
      "value": "false"
    },
    {
      "name": "diuretics_history",
      "value": "false"
    }
  ]
}
Name Type Description
empi_id string ID of the persons within the HealtheIntent population
normalized_risk_score string Value from 0-100 representing the percentage likelihood the person will be readmitted. Scores are normalized against the entire readmission patient population.
date string Indicates the date and time (ISO-8601 format) the score was calculated.
stratification string Normalized scores are stratified into 3 risk levels: LOW MODERATE HIGH. The score ranges are configurable per client, but defaults to LOW (> 0 AND <=40), MODERATE (> 40 AND <= 60) HIGH (> 60).
risk_factors array Collection of name value pairs used to calculate the score.

List of Person Readmission Risk Scores

Example Request

require 'httparty'

HTTParty.post(
    'https://cernerdemo.programs.healtheintent.com/api/populations/0a9cc467-094c-403a-84d0-35604e1e418c/readmission_risk',
    headers: { 'Content-Type' => 'application/json', 'Authorization' => 'Auth Header' },
    body: {empi_ids: ['0655eafe-a71e-3b55-8258-2a51f43b14fc', '00e4fd48-efe7-301c-89bb-5f6d77312373']}.to_json
)
curl -H 'Authorization: <auth_header>' -H 'Content-Type: application/json' -X POST -d '{"empi_ids":["0655eafe-a71e-3b55-8258-2a51f43b14fc","00e4fd48-efe7-301c-89bb-5f6d77312373"]}' https://cernerdemo.programs.healtheintent.com/api/populations/0a9cc467-094c-403a-84d0-35604e1e418c/readmission_risk

Example Response

{
  "readmission_risk": [
    {
      "empi_id": "00e4fd48-efe7-301c-89bb-5f6d77312373",
      "normalized_risk_score": "39",
      "date": "2016-10-29T00:00:00.000Z",
      "stratification": "LOW",
      "risk_factors": [
        {
          "name": "age_in_years",
          "value": "32"
        },
        {
          "name": "insurance",
          "value": "MEDICAID"
        },
        {
          "name": "er_in_last_six_months",
          "value": "false"
        },
        {
          "name": "inpatient_in_last_six_months",
          "value": "true"
        },
        {
          "name": "diuretics_current",
          "value": "false"
        },
        {
          "name": "diuretics_history",
          "value": "false"
        }
      ]
    },
    {
      "empi_id": "0655eafe-a71e-3b55-8258-2a51f43b14fc",
      "normalized_risk_score": "62",
      "date": "2016-11-01T00:00:00.000Z",
      "stratification": "HIGH",
      "risk_factors": [
        {
          "name": "age_in_years",
          "value": "85"
        },
        {
          "name": "insurance",
          "value": "MEDICARE"
        },
        {
          "name": "er_in_last_six_months",
          "value": "false"
        },
        {
          "name": "inpatient_in_last_six_months",
          "value": "true"
        },
        {
          "name": "bmi",
          "value": "25.39",
          "interpretation": "overweight"
        },
        {
          "name": "diuretics_current",
          "value": "false"
        },
        {
          "name": "diuretics_history",
          "value": "false"
        }
      ]
    }
  ],
  "more_results": false,
  "total_results": 2
}

POST https://{client}.programs.healtheintent.com/api/populations/{population_id}/readmission_risk

Retrieves the most recent Readmission Risk Scores for a given list of persons within a population.

Path Parameters

Parameter Description
population_id The HealtheIntent population ID

Request Message Body

A JSON array of person IDs.

Name Type Description
empi_ids array: string IDs of persons within the HealtheIntent population

Responses

Status Type Description
200 ReadmissionRiskScores Collection of Readmission Risk Scores
400 string Bad Request
401 string Unauthorized
403 string Forbidden
404 string Not Found
500 string Internal Server Error

Retrieves a Person’s Historical Readmission Risk Scores

Example Request

curl -H 'Authorization: <auth_header>' https://cernerdemo.programs.healtheintent.com/api/populations/0a9cc467-094c-403a-84d0-35604e1e418c/readmission_risk/0655eafe-a71e-3b55-8258-2a51f43b14fc?start_version=201600000000&end_version=201700000000&limit=2
require 'httparty'

HTTParty.get(
  'https://cernerdemo.programs.healtheintent.com/api/populations/0a9cc467-094c-403a-84d0-35604e1e418c/readmission_risk/0655eafe-a71e-3b55-8258-2a51f43b14fc?start_version=201600000000&end_version=201700000000&limit=2',
  headers: { 'Authorization' => '<auth_header>' }
)

Example Response

{
  "readmission_risk": [
    {
      "empi_id": "0655eafe-a71e-3b55-8258-2a51f43b14fc",
      "normalized_risk_score": "62",
      "date": "2016-10-31T23:00:00.000Z",
      "stratification": "HIGH",
      "risk_factors": [
        {
          "name": "age_in_years",
          "value": "85"
        },
        {
          "name": "insurance",
          "value": "MEDICARE"
        },
        {
          "name": "er_in_last_six_months",
          "value": "false"
        },
        {
          "name": "inpatient_in_last_six_months",
          "value": "true"
        },
        {
          "name": "bmi",
          "value": "25.39",
          "interpretation": "overweight"
        },
        {
          "name": "diuretics_current",
          "value": "false"
        },
        {
          "name": "diuretics_history",
          "value": "false"
        },
      ]
    },
    {
      "empi_id": "0655eafe-a71e-3b55-8258-2a51f43b14fc",
      "normalized_risk_score": "44",
      "date": "2016-04-23T00:00:00.000Z",
      "stratification": "MODERATE",
      "risk_factors": [
        {
          "name": "age_in_years",
          "value": "84"
        },
        {
          "name": "insurance",
          "value": "MEDICARE"
        },
        {
          "name": "er_in_last_six_months",
          "value": "false"
        },
        {
          "name": "inpatient_in_last_six_months",
          "value": "false"
        },
        {
          "name": "bmi",
          "value": "24.62",
          "interpretation": "overweight"
        },
        {
          "name": "diuretics_current",
          "value": "false"
        },
        {
          "name": "diuretics_history",
          "value": "false"
        }
      ]
    }
  ],
  "more_results": true,
  "total_results": 20
}

GET https://{client}.registries.healtheintent.com/api/populations/{population_id}/readmission_risk/{person_id}

Retrieves historical Readmission Risk Scores for a person within a population.

Path Parameters

Parameter Description
population_id The HealtheIntent population ID
person_id The HealtheIntent person ID

Query Parameters

Parameter Default Description
start_version If not set, only the most recent score is returned string Filters the results based on the time the risk scores were calculated. The start time in YYYYMMDDhhmm format UTC. Required if end_version is also set.
end_version If not set, only the most recent score is returned string Filters the results based on the time the risk scores were calculated. The end time in YYYYMMDDhhmm format UTC. Required if start_version is also set.
start 0 integer Index of result to begin retrieving results at. Defaults to 0.
limit 20 integer Maximum number of results to retrieve. Must be between 1 and 500, defaults to 100.

Responses

Status Type Description
200 ReadmissionRiskScores collection of Readmission Risk Scores
400 string Bad Request
401 string Unauthorized
403 string Forbidden
404 string Not Found
500 string Internal Server Error

Readmission Risk API Definitions

PersonIdResponse

Name Type Description
empi_ids array: HealtheIntentPersonId Collection of HealtheIntent person ID objects

HealtheIntentPersonId

Name Type Description
value `string’ The local ID corresponding to the Person
empi_id string If SUCCESS, ID of the person within the HealtheIntent population.
status string SUCCESS or FAILURE
message ‘string’ If FAILURE, additional information related to the failed HealtheIntent ID lookup.

ReadmissionRiskScores

Name Type Description
readmission_risk array: ReadmissionRiskScore Collection of Readmission Risk Score objects
more_results boolean Boolean indicating if more results could be retrieved via paging
total_results integer Total number of results for the criteria passed

ReadmissionRiskScore

Name Type Description
empi_id string ID of the person within the HealtheIntent population
normalized_risk_score string Value from 0-100 representing the percentage likelihood the person will be readmitted. Scores are normalized against the entire readmission patient population.
date string Indicates the date and time (ISO-8601 format) the score was calculated.
stratification string Normalized scores are stratified into 3 risk levels: LOW, MODERATE, HIGH. The score ranges are configurable per client, but defaults to LOW (> 0 AND <=40), MODERATE (> 40 AND <= 60) HIGH (> 60).
risk_factors array: ReadmissionRiskFactor Collection of Readmission Risk Factor objects

ReadmissionRiskFactor

Name Type Description
name string Name of the risk factor. See ReadmissionRiskFactorReference for more details.
value string Value of the risk factor. See ReadmissionRiskFactorReference for more details.
interpretation string (Optional) Interpretation of the risk factor. See ReadmissionRiskFactorReference for more details.

ReadmissionRiskFactorReference

This table details possible values for fields in the ReadmissionRiskFactor object.

Name Description Value Interpretation Example ReadmissionRiskFactor object
acuity Qualifying encounter has admission type of ‘EMERGENT’ or ‘URGENT’ Possible values of true or false {"name": "acuity","value": "true"}
age_in_years Person’s age Whole number. Values range from 0 to 130 {"name": "age_in_years","value": "30"}
ama_history Number of encounters that were discharged with disposition of “AMA” in the past year Whole number. Example: 1 {"name": "ama_history","value": "1"}
bmi Latest BMI measured during encounter Decimal number. Example: 25.39 Possible values of normal, overweight, obese, other {"name": "bmi","value": "25", "interpretation": "normal"}
comorbidity_index Number of comorbidity conditions and comorbidity procedures that the patient has been diagnosed with in the last 12 months Whole number. Example: 1 {"name": "comorbidity_index","value": "0"}
diuretics_current Diuretic medications started after the start of the qualifying encounter and started before the discharge date/time Possible values of true or false {"name": "diuretics_current","value": "false"}
diuretics_history Diuretic medications started anytime in the year preceding the start of the qualifying encounter Possible values of true or false {"name": "diuretics_history","value": "false"}
er_in_last_six_months Person has had an ER visit in past 6 months prior to this encounter Possible values of true or false {"name": "er_in_last_six_months","value": "false"}
heparin_current Heparin medications started after the start of the qualifying encounter and started before the discharge date/time Possible values of true or false {"name": "heparin_current","value": "false"}
inpatient_in_last_six_months Person has had an Inpatient visit in past 6 months prior to this encounter Possible values of true or false {"name": "inpatient_in_last_six_months","value": "false"}
insulin_current Insulin medications started after the start of the qualifying encounter and started before the discharge date/time Possible values of true or false {"name": "insulin_current","value": "true"}
insulin_history Insulin medications started anytime in the year preceding the start of the qualifying encounter Possible values of true or false {"name": "insulin_history","value": "true"}
insurance Type of insurance Possible values of commercial, medicaid, medicare, self_pay, other {"name": "insurance","value": "medicaid"}
observation_in_last_six_months Person has had an Observation visit in past 6 months prior to this encounter Possible values of true or false {"name": "observation_in_last_six_months","value": "false"}
platelet_ag_current Platelet ag medications started after the start of the qualifying encounter and started before the discharge date/time Possible values of true or false {"name": "platelet_ag_current","value": "false"}
platelet_ag_history Platelet ag medications started anytime in the year preceding the start of the qualifying encounter Possible values of true or false {"name": "platelet_ag_history","value": "true"}
snf_admit_source Qualifying encounter has admit source of “TRANSFER_FROM_SNF” Possible values of true or false {"name": "snf_admit_source","value": "false"}