Accordion APIs How-To series, part I

The first few steps to access Accordion APIs

As some of you may already know, we recently launched one of the first-in-the-industry predictive APIs for value-based reimbursement (see here for more details). Many people and organizations expressed their excitement, and asked how they can use the APIs.

Today, we will go through a step-by-step tutorial of how healthcare innovators can use our APIs to make awesome applications. This is the first post in the Accordion APIs How-To series. After following this tutorial, you will be able to

• Update your password (and other user information)
• Request JSON Web Tokens
• Access Accordion predictive APIs

If you don’t have an account yet, please contact us at info@accordionhealth.com to create one!

Update your password

With the account you created, you must first update your password. To do so, you just need to send a PUT /api/user-info with your username, password, and new password in the request body.

PUT /api/user-info HTTP/1.1
Host: developers.accordionhealth.com
Content-Type: application/json
{
  "username": "john.doe@example.com",
  "password": "A-unique-default-password-01123",
  "newPassword": "John-Doe-5813"
}

If the credentials are correct, you will see the response as follows.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "fieldsUpdated": ["password", "passwordUpdated"]
}

If you see passwordUpdated in fieldsUpdated, then you have successfully updated your password.

Request a JWT

Our next step is to request a JSON Web Token (JWT). Our APIs use the token-based authentication framework; thus, you will need a JWT before you can access them.

Let’s send a POST /api/token with your username and new password attached in the request body.

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

If successful, you will see the JWT with your access limit and current usage as follows.

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

A few things to keep in mind:

1. accessLimit tells you the maximum number of successful requests you can make with the current subscription.
2. totalUsage shows the total number of successful requests you have made so far.

Note that successful requests are the requests that receive HTTP/1.1 200 OK response code, and do not include the PUT /api/user-info and POST /api/token requests.

Take a peek at the Risk Profiler

Congratulations! Now the green light is on. You can start using the APIs to build your own applications.

Before we end this post, let’s use the JWT you just received and play with it a bit. The example below shows how you can use our Risk Profiler to estimate the HCC risk scores of your members.

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
    }
  ],
  "riskModel": "cms_hcc22",
  "ICDVersion": "9"
}

Please note that there is a space between Bearer and JSON.WEB.TOKEN.

If successful, your response should look as follows.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "riskScore": 0.406,
  "currentHCC: [
    "[CC19] Diabetes without Complication"
  ],
  "numHCC": 1
}

What’s next?

In this post, we briefly covered the first few steps for using the Accordion predictive APIs. In the next post of the series, we will dig deep into our Risk Profiler, Quality Profiler and other predictive analytics APIs. Stay tuned!

For more information, please contact info@accordionhealth.com or visit our API documentation at developers.accordionhealth.com.