NAV
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 that represents the likelihood of readmission for the patient.

Readmission Person

Readmission 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 Oracle Health Data Intelligence collects data from many different sources, Cerner uses one ID to consolidate the information. Readmission Risk Score endpoints require the patient’s Health Data Intelligence ID, which can be found in the patient’s source ID (typically the ID in the electronic health record). If the person ID will be used to retrieve readmission data, retrieve the person ID using the Readmission Person ID Lookup endpoint. This Readmission Person ID Lookup endpoint is used to generate a person in the readmission context.

Note: You must use the Readmission Person ID Lookup endpoint to retrieve the person ID that you need for the other requests for the legacy Readmission Risk API. You cannot use the patient ID retrieved using the Patient API.

Path Parameters

Parameter Description
population_id The Health Data Intelligence 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 data.

Responses

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

Readmission Risk Score

The Readmission Risk Score object contains a patient’s risk score information and the factors used to calculate the score. The API can be used to retrieve current readmission risk scores and historical scores for a single patient or multiple patients.

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 The ID of the patient in the Health Data Intelligence population from the Readmission Person ID Lookup endpoint. See the Readmission Person ID Lookup section for more information.
normalized_risk_score string The value from 0 through 100 representing the percentage likelihood the patient will be readmitted. Scores are normalized against the entire readmission patient population.
date string Indicates the date and time the score was calculated. The date and time format is in ISO-8601 (International Organization for Standardization).
stratification string Normalized scores are stratified into three risk levels: LOW, MODERATE, and HIGH. The score ranges are configurable for each client, but the stratification defaults to LOW (greater than 0 and less than or equal to 40), MODERATE (greater than 40 and less than or equal to 60), and HIGH (greater than 60).
risk_factors array The collection of name value pairs used to calculate the score.

Readmission Risk Batch

Example Request

curl -H 'Authorization: <auth_header>' https://cernerdemo.programs.healtheintent.com/api/populations/0a9cc467-094c-403a-84d0-35604e1e418c/readmission_risk/versions/201600000000%3A201700000000?start=0&limit=2

require 'httparty'

HTTParty.get(
  'https://cernerdemo.programs.healtheintent.com/api/populations/0a9cc467-094c-403a-84d0-35604e1e418c/readmission_risk/versions/201600000000%3A201700000000?start=0&limit=2',
  headers: { 'Authorization' => '<auth_header>' }
)

Example Response

{
    "readmission_risk_scores": [
        {
            "version_id": "201600000000:201700000000:003a1dfa-9743-3518-91dc-244f57ed282f",
            "person_id": "839932",
            "encounter_id": "2107912",
            "date": "2016-08-05T06:00:00.000Z",
            "raw_risk_score": "0.0254004581513766",
            "normalized_risk_score": "27",
            "stratification": "LOW"
        },
        {
            "version_id": "201600000000:201700000000:005249b9-a06f-32f3-b378-b6495d5b238f",
            "person_id": "3108014",
            "encounter_id": "2903915",
            "date": "2016-08-05T06:00:00.000Z",
            "raw_risk_score": "0.00396696473526762",
            "normalized_risk_score": "21",
            "stratification": "LOW"
        }
 ],
  "total_count": 2,
  "more_results": true,
  "total_results": 558279
}

GET https://{client}.programs.healtheintent.com/api/populations/{population_id}/readmission_risk/versions/{version}

Retrieves a readmission risk batch associated with a population and a range of versions.

Path Parameters

Parameter Description
population_id The Health Data Intelligence population ID.
version The Health Data Intelligence batch version.

Query Parameters

Parameter Default Type Description
start 0 integer The index of result to begin retrieving results at. Default settings are set to 0.
limit 20 integer The maximum number of results to retrieve. Must be between 1 and 500. Default settings are set to 100.

Responses

Status Type Description
200 ReadmissionRiskBatchScores Readmission Risk batch associated with population and version.
400 string Bad Request
401 string Unauthorized
403 string Forbidden
404 string Not Found
500 string Internal Server Error

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 patients in a population.

Path Parameters

Parameter Description
population_id The Health Data Intelligence population ID.

Request Message Body

A JSON array of person IDs.

Name Type Description
empi_ids array: string The person IDs in the Health Data Intelligence population from the Readmission Person ID Lookup endpoint. See the Readmission Person ID Lookup section for more information.

Responses

Status Type Description
200 ReadmissionRiskScores The 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 the Historical Readmission Risk Scores of a Patient

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=1

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=1',
  headers: { 'Authorization' => '<auth_header>' }
)

Example Response

{
  "readmission_risk": [
    {
      "empi_id": "027eca68-09d8-30f5-9ee9-644b99447d8b",
      "normalized_risk_score": "36",
      "date": "2017-08-29T01:00:00.000Z",
      "stratification": "LOW",
      "risk_factors": [
        {
          "name": "age_in_years",
          "value": "56"
        },
        {
          "name": "insurance",
          "value": "SELF_PAY"
        },
        {
          "name": "ama_history",
          "value": "0"
        },
        {
          "name": "acuity",
          "value": "false"
        },
        {
          "name": "er_in_last_six_months",
          "value": "false"
        },
        {
          "name": "snf_admit_source",
          "value": "false"
        },
        {
          "name": "inpatient_in_last_six_months",
          "value": "true"
        },
        {
          "name": "observation_in_last_six_months",
          "value": "false"
        },
        {
          "name": "comorbidity_index",
          "value": "4"
        },
        {
          "name": "diuretics_current",
          "value": "false"
        },
        {
          "name": "heparin_current",
          "value": "false"
        },
        {
          "name": "insulin_current",
          "value": "false"
        },
        {
          "name": "platelet_ag_current",
          "value": "false"
        },
        {
          "name": "diuretics_history",
          "value": "true"
        },
        {
          "name": "insulin_history",
          "value": "false"
        },
        {
          "name": "platelet_ag_history",
          "value": "true"
        }
      ]
    }
  ],
  "more_results": false,
  "total_results": 1
}

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

Retrieves historical readmission risk scores for a patient in a population.

Path Parameters

Parameter Description
population_id The Health Data Intelligence population ID.
person_id The person ID in the Health Data Intelligence population from the Readmission Person ID Lookup endpoint. See the Readmission Person ID Lookup section for more information.

Query Parameters

Parameter Default Type Description
start_version If not set, only the most recent score is displayed. string This parameter filters the results based on the time the risk scores were calculated. The start time in YYYYMMDDhhmm format, Coordinated Universal Time (UTC). This is required if the end_version parameter is also set.
end_version If not set, only the most recent score is displayed. string This parameter filters the results based on the time the risk scores were calculated. The end time is in YYYYMMDDhhmm format, UTC. This is required if the start_version parameter is also set.
start 0 integer The index of result to begin retrieving results at. The default settings are set to 0.
limit 20 integer The maximum number of results to retrieve. Must be between 1 and 500. The default settings are set to 100.

Responses

Status Type Description
200 ReadmissionRiskScores The 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 Contains the collection of Oracle Health Data Intelligence person ID objects retrieved from the Readmission Person ID Lookup endpoint. See the Readmission Person ID Lookup section for more information.

HealtheIntentPersonId

Name Type Description
value `string’ The local ID corresponding to the person data.
empi_id string If a status of SUCCESS is displayed, this parameter represents the ID of the person in the Health Data Intelligence readmission population.
status string Two statuses are available, SUCCESS or FAILURE.
message ‘string’ If a status of FAILURE is displayed, this parameter represents additional information related to the failed Health Data Intelligence ID lookup.

ReadmissionRiskScores

Name Type Description
readmission_risk array: ReadmissionRiskScore Contains a collection of Readmission Risk Score objects.
more_results boolean The Boolean indicating if more results can be retrieved through paging.
total_results integer The total number of results for the criteria passed.

ReadmissionRiskScore

Name Type Description
empi_id string The ID of the patient in the Health Data Intelligence population retrieved from the Readmission Person ID Lookup endpoint. See the Readmission Person ID Lookup section for more information.
normalized_risk_score string The value from 0 through 100 that represents the percentage likelihood that the patient will be readmitted. Scores are normalized against the entire readmission patient population.
date string This parameter indicates the date and time in ISO-8601 format (International Organization for Standardization) that the score was calculated.
stratification string The normalized scores that are stratified into three risk levels: LOW, MODERATE, and HIGH. The score ranges are configurable for each client, but defaults to LOW (greater than 0 and less than or equal to 40), MODERATE (greater than 40 and less than or equal to 60), and HIGH (greater than 60).
risk_factors array: ReadmissionRiskFactor Contains the collection of Readmission Risk Factor objects.

ReadmissionRiskBatchScores

Name Type Description
readmission_risk array: See ReadmissionRiskBatch Contains a collection of Readmission Risk Score objects.
more_results boolean The Boolean indicating if more results could be retrieved using paging.
total_results integer The total number of results for the criteria passed.

ReadmissionRiskBatch

Name Type Description
version_id string Contains the version that consists of nominal time and empi_id data in this format(nominalTime:empiid).
person_id string The person ID in the Health Data Intelligence population retrieved from the Readmission Person ID Lookup endpoint. See the Readmission Person ID Lookup section for more information.
encounter_id string The encounter ID of the patient.
date string The date of the readmission risk batch.
raw_risk_score string The raw readmission risk score.
normalized_risk_score string The value from 0 through 100 that represents the percentage likelihood that the patient will be readmitted. Scores are normalized against the entire readmission patient population.
stratification string The normalized scores are stratified into tree risk levels: LOW, MODERATE, and HIGH. The score ranges are configurable for each client, but defaults to LOW (greater than 0 and less than or equal to 40), MODERATE (greater than 40 and less than or equal to 60), and HIGH (greater than 60).

ReadmissionRiskFactor

Name Type Description
name string The name of the risk factor. See ReadmissionRiskFactorReference for more details.
value string The value of the risk factor. See ReadmissionRiskFactorReference for more details.
interpretation string The interpretation of the risk factor. See ReadmissionRiskFactorReference for more details. This parameter is optional.

ReadmissionRiskFactorReference

The table below provides details about possible values for fields in the ReadmissionRiskFactor object.

Name Description Value Interpretation Example ReadmissionRiskFactor object
acuity The qualifying encounter has admission type of ‘EMERGENT’ or ‘URGENT’. Possible values of true or false {"name": "acuity","value": "true"}
age_in_years The age of the patient. Whole number. Values range from 0 to 130 {"name": "age_in_years","value": "30"}
ama_history The number of encounters that were discharged with disposition of “AMA” in the past year. Whole number. Example: 1 {"name": "ama_history","value": "1"}
bmi The latest body mass index (BMI) measured during encounter. Decimal number. Example: 25.39. Possible values of normal, overweight, obese, other {"name": "bmi","value": "25", "interpretation": "normal"}
comorbidity_index The 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 that were started after the start of the qualifying encounter and started before the discharge date and time. Possible values of true or false {"name": "diuretics_current","value": "false"}
diuretics_history Diuretic medications that were 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 The value that represents that if the person has had an emergency room (ER) visit in past six months before this encounter. Possible values of true or false {"name": "er_in_last_six_months","value": "false"}
heparin_current Heparin medications that were started after the start of the qualifying encounter and started before the discharge date and time. Possible values of true or false {"name": "heparin_current","value": "false"}
inpatient_in_last_six_months The value that represents if the person has had an inpatient visit in past six months before this encounter. Possible values of true or false {"name": "inpatient_in_last_six_months","value": "false"}
insulin_current Insulin medications that were started after the start of the qualifying encounter and started before the discharge date and time. Possible values of true or false {"name": "insulin_current","value": "true"}
insulin_history Insulin medications that were started anytime in the year preceding the start of the qualifying encounter. Possible values of true or false {"name": "insulin_history","value": "true"}
insurance The type of insurance. Possible values of commercial, medicaid, medicare, self_pay, other {"name": "insurance","value": "medicaid"}
observation_in_last_six_months The value that represents if the person has had an observation visit in past six months before this encounter. Possible values of true or false {"name": "observation_in_last_six_months","value": "false"}
platelet_ag_current Platelet aggregation (ag) medications that were started after the start of the qualifying encounter and started before the discharge date and time. Possible values of true or false {"name": "platelet_ag_current","value": "false"}
platelet_ag_history Platelet ag medications that were 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 The qualifying encounter that has an admit source of “TRANSFER_FROM_SNF”. Possible values of true or false {"name": "snf_admit_source","value": "false"}
ruby shell