Accordion APIs How-To series, part II

Understanding the risk conditions of your population

In the last post of the Accordion APIs How-To series, we covered how you can update your account information, and request and use JWTs to access our predictive APIs.

Today, we will dig deeper into our Risk Profiler and see how we can:

• Estimate members’ Hierarchical Condition Category (HCC) risk scores
• Identify members’ existing Hierarchical Condition Categories

Before we start, let’s send a POST /api/token to obtain a JWT and use it throughout the entire post.

POST /api/token HTTP/1.1
Host: developers.accordionhealth.com
Content-Type: application/json
{
  "username": "john.doe@example.com",
  "password": "John-Doe-5813"
}

You will receive your JWT in the response.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "accessToken": "JSON.WEB.TOKEN",
  "accessLimit": 15000,
  "totalUsage": 1
}

Risk Profiler basic requirements

Suppose you want to identify risk conditions of a Medicare Advantage plan member, and you have access to the information such as demographics, medical claims, or electronic health records.

Normally, you would need to write very complex SQL scripts, debug databases, and struggle with the numbers and spreadsheets that you may not fully understand. However, with our Risk Profiler APIs, this task becomes very easy.

First, you gather the member’s demographics, insurance eligibility and diagnosis codes. Next, pick a risk adjustment model, e.g. cms_hcc21, cms_hcc22, hhs_hcc15 or hhs_hcc16. With them in hands, let’s construct a parameter JSON as follows.

// Fields in the request body to the Risk Profiler
{
  "gender": "female",
  "age": 65,
  "medicaidEnrollment": false,
  "newEnrollee": false,
  "SNP": false,
  "ESRD": false,
  "lowIncome": false,
  "OREC": "0",
  "diagnosisCodes": [
    {
      "code": "9-25000",
      "count": 1
    },
    {
      "code": "9-1982",
      "count": 1
    }
  ],
  "riskModel": "cms_hcc22"
}

A few things to keep in mind:

1. All fields have pre-specified types (and formats if they are Strings). If any of the fields don’t meet the requirements, you will receive a 400 BAD REQUEST. Please make sure to follow these field requirements before you send a request.
2. Not all of the fields are required. You can skip the optional fields if you are okay with the default values, but that might affect your results.
3. For each diagnosis code in diagnosisCodes, you need to add the International Classification of Diseases (ICD) version followed by a hyphen as the prefix and remove any dots from the code. For instance, "9-25000" stands for the ICD-9 diagnosis code 250.00, and "9-1982" stands for the ICD-9 diagnosis code 198.2. Also, specify how many the member has been diagnosed with such disease/condition in "count".

For more information about the requirements, please visit our API documentation at developers.accordionhealth.com.

Risk scores and existing Hierarchical Condition Categories

In our Risk Profiler APIs, /api/current-hcc estimates the risk scores and identifies the existing HCCs based on the provided information.

To obtain the risk scores and risk conditions, send a POST /api/current-hcc with the well-formatted request body and JWT you received earlier.

POST /api/current-hcc HTTP/1.1
Host: developers.accordionhealth.com
Content-Type: application/json
Authorization: Bearer JSON.WEB.TOKEN
{
  "gender": "female",
  "age": 65,
  "medicaidEnrollment": false,
  "newEnrollee": false,
  "SNP": false,
  "ESRD": false,
  "lowIncome": false,
  "OREC": "0",
  "diagnosisCodes": [
    {
      "code": "9-25000",
      "count": 1
    },
    {
      "code": "9-1982",
      "count": 1
    }
  ],
  "riskModel": "cms_hcc22"
}

A successful response would look as follows.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "currentHCC": [
    "[CC19] Diabetes without Complication",
    "[CC10] Lymphoma and Other Cancers"
  ],
  "numHCC": 2
  "riskScore": 1.078
}

Voila! You just identified two risk conditions and estimated the risk score of the member. According to the response, the member has diabetes and lymphoma, and her risk score is 1.078.

In this example, we assumed that this member was in a Medicare Advantage plan, and therefore chose the riskModel to be cms_hcc22. If you want to estimate the risk conditions of members in an ACA plan, you can simply set the riskModel to be hhs_hcc16 and choose the appropriate metal level hixPlate (the default is s or silver).

What’s next?

Today, we illustrated how to get a good understanding of the members’ risk conditions by using /api/current-hcc.

Coming up next, we will move on to the predictive side of our Risk Profiler APIs. These APIs can suggest missing or hidden diagnosis codes that will substantially improve the accuracies of the risk scores.

See you next week!