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"} |