This is the FHIR R4 (v2) documentation for the Blue Button API.

If needed, documentation for the STU3 (v1) implementation of the Blue Button API is available.

Try the API

You can start using the API right away by following these steps:

  1. Join the Developer Sandbox & register a Sandbox application
  2. Generate a sample token
  3. Call the API to retrieve synthetic data for a sample Patient
  4. Review the response data
  5. Access the synthetic dataset to try additional calls

Step 1: Join the Developer Sandbox and register a Sandbox application

You will need to create an account to join the Developer Sandbox. Once you have verified your account, log in and click “Add an Application” from the Developer Sandbox homepage.

Register a new Sandbox application to get a Client ID and Client Secret. You can also use one of the Blue Button Sample Applications.

The OAuth screen with a choice for benes to share or withhold certain demographic information

You need to include at least one Callback or Redirect URL.

You can change any of this information later in My Sandbox Apps.

Step 2: Generate a sample token

To test out the Blue Button API, you must first generate a sample token that represents a beneficiary granting consent to access their CMS Medicare claims data.

Access the Test Client to see a sample of Blue Button data.

  1. If you are already logged in to the Developer portal, log out.
  2. From the Sandbox homepage, click on “Test Client” in the top-level navigation.
  3. Click “Get a Sample Authorization Token” if you want to call v1 API or “Get a Sample Authorization Token for v2” if want to call v2 API: The sample authorization token page
  4. Click the “Authorize as a Beneficiary” at the bottom to authorize
v1 v2
v1 sample API call v2 sample API call

5.You will be redirected to the login page for Medicare.gov. Medicare.gov login page 6.Log in with one of the Synthetic Beneficiary Accounts:

Synthetic Beneficiary Accounts The first user is BBUser00000 with password PW00000! Sample users continue all the way to BBUser29999 with password PW29999! Note: the ! at the end of the password is required.

  1. Depending on your application, you can select either “Share all of your data” or “Share healthcare data, but not your personal info” to test your application.
  2. Click “Allow” to Authorize sharing data. Medicare.gov authorization page
  3. Review the details returned from the Authorization flow: access token and its info, patient ID, scopes associated with the token etc.
v1 v2
v1 Authorization flow return v2 Authorization flow return
  1. Switching from v2 to v1 or vice versa, on authorization details page (step 7) there are two links: “repeat this step if you need a new token” - click this link, you will be directed to authorize as a beneficiary as in step 4 and stay with your current API version. “restart testclient” - click this link, you will be directed to test client home page as in step 3 and choose v1 or v2 API there. Authorization details page displaying action items

Step 3: Call the API

After you obtain your Access Token, you can call the API using Postman or cURL.

To call the API using Postman:

  1. From the Postman app, open a new tab
  2. Paste the Request URL:

for v1: https://sandbox.bluebutton.cms.gov/v1/fhir/Patient/-20140000008325

for v2: https://sandbox.bluebutton.cms.gov/v2/fhir/Patient/-20140000008325

  1. Click “Authorization” and select type “OAuth 2.0”
  2. Click on “Get New Access Token”

5.Enter the following parameters:

Token Name: {The name of your app}

Grant Type: Authorization Code (unless you have chosen an alternate value for your app)

Callback URL: One of the redirect uris you registered for your app, for example:

http://localhost:3000

Auth URL:

for v1: https://sandbox.bluebutton.cms.gov/v1/o/authorize/

for v2: https://sandbox.bluebutton.cms.gov/v2/o/authorize/

Access Token URL:

for v1: https://sandbox.bluebutton.cms.gov/v1/o/token/

for v2: https://sandbox.bluebutton.cms.gov/v2/o/token/

Client ID: {The Client ID assigned to your App in the sandbox}

Client Secret: {The Client Secret assigned to your App in the sandbox}

Scope:

patient/Patient.read patient/Coverage.read patient/ExplanationOfBenefit.read profile

NOTE: When a beneficiary is authorizing your application, they will have the ability to omit the patient/Patient.read scope. Be sure that you build your application accordingly to handle a 403 error if a beneficiary decides to filter their demographic information.

State: An optional value that you may use in your app

Client Authentication: Select “Send as Basic Auth header”

for v1: https://sandbox.bluebutton.cms.gov/v1/o/authorize/

for v2: https://sandbox.bluebutton.cms.gov/v2/o/authorize/

6.Click Request Token. You should see a pop up for your Medicare account. Login using one of the Synthetic Beneficiary Accounts

Synthetic Beneficiary Accounts

The first user is BBUser00000 with password PW00000! Sample users continue all the way to BBUser29999 with password PW29999! Note: the ! at the end of the password is required

  1. Authorize sharing by clicking “Allow” on the authorization screen
  2. When you return to the Postman workspace you should now be able to make requests to the API using the Access Token that will have been placed in the Header
  3. Click “Send” and see the synthetic beneficiary's personal health information as a Patient FHIR Resource display under “Body” in Postman

You can also use cURL:

for v1: curl –header “Authorization: Bearer YOUR TOKEN HERE” https://sandbox.bluebutton.cms.gov/v1/fhir/Patient/-20140000008325

for v2: curl –header “Authorization: Bearer YOUR TOKEN HERE” https://sandbox.bluebutton.cms.gov/v2/fhir/Patient/-20140000008325

Step 4: View the API Response

Step 5: Access Synthetic Data

In order to access the full synthetic dataset for an individual synthetic beneficiary, you can do the following:

  1. Set up your sandbox application
  2. Log out of https://sandbox.bluebutton.cms.gov.

  3. Access the authorization url at:

for v1 https://sandbox.bluebutton.cms.gov/v1/o/authorize/

for v2 https://sandbox.bluebutton.cms.gov/v2/o/authorize/

Note: The last backslash is important. Also remember to append ?client_id={your client_id assigned to the application you registered}

  1. You will be redirected to the Medicare authentication screen on. DO NOT ACCESS THIS PAGE DIRECTLY.

5.Use one of thirty thousand provided usernames and passwords.

Synthetic Beneficiary Accounts

The first user is BBUser00000 with password PW00000! Sample users continue all the way to BBUser29999 with password PW29999! Note: the ! at the end of the password is required

6.Approve access for your application, which will now receive an access token, which can be used in the requests described above.

  1. The authorization completes when you are redirected back to the Redirect_URI you specified when you registered your application.

Authorization

To use the Blue Button 2.0 OAuth 2 a developer must register their application.

A registered application is given a Client ID and a Client Secret. The secret should only be used if it can be kept confidential, such as communication between your server and the Blue Button 2.0 API. Otherwise the Client Application Flow may be used.

Scopes

Access tokens have a scope, which defines what the access token can do and what resources it can access. For our purposes, scopes are primarily utilized to give Medicare beneficiaries more granular choice over what data they would like to share with applications. The Blue Button 2.0 API has implemented HL7 FHIR Scopes to manage access to beneficiary data. They look like this:

patient/Patient.read

patient/Coverage.read

patient/ExplanationOfBenefit.read

From the OpenID Connect specification we support:

profile

This gives access to the /v1/connect/UserInfo or /v2/connect/UserInfo Endpoint.

Our OAuth screen gives beneficiaries the ability to choose whether or not to share their demographic information. Your application will need to handle the return of a 403 status code from the /v1/fhir/Patient (or /v2/fhir/Patient) and /v1/connect/userinfo (or /v2/connect/userinfo) endpoints.

The OAuth screen with a choice for benes to share or withhold certain demographic information

If the beneficiary declines to share information that your application needs to function, you may display a message explaining why that information is needed and request reauthorization, or handle the collection of that information elsewhere within your application.

The default selection when a beneficiary reaches the authorization screen will be to share all data, including demographic data, with your application. If a beneficiary makes a selection as to whether or not they want to share demographic data with your application and later decides they want to change that selection, they'll need to be taken through the authorization flow again to make a different choice from the OAuth screen.

Ensuring you still get the data you need

Take the time to ensure that you have fallbacks in place if you are unable to access the patient or userinfo endpoints.

For example, if you are getting the patient_ID from the v1/fhir/Patient (or v2/fhir/Patient) endpoint, we recommend getting that identifier from the initial authorization response, or another resource like ExplanationOfBenefit or Coverage.

Explanation of needed data to Medicare Beneficiaries

If information limited by a scope is required for your application to properly function and it is not possible to get the information in another endpoint, we recommend providing an explanation about why certain data is needed in your user flow.

For example, if you use demographic information to help beneficiaries autofill tedious data-entry, you might want to explain that benefit before they reach the authorization screen. It is essential, however, that you give beneficiaries the full picture. If they do share that data with you for one-time data entry, they should know how long you keep it and if it is used for any other purposes.

What if my application doesn't need demographic information from beneficiaries?

As stewards of sensitive data, it is important to adopt the practice of only asking for the data that is needed to perform a service for a beneficiary. As you register or edit an application in our Sandbox, you will see an option to choose whether or not your application needs to collect demographic information from beneficiaries.

If you choose not to collect demographic information, Medicare beneficiaries will see a simplified version of the OAuth screen as they no longer need to choose whether or not they want to share that information.

Native Mobile App Support

Native Mobile App Support follows the RFC 8252 - OAuth 2.0 for Native Apps authentication flow utilizing the PKCE extension and enables a custom URI scheme redirect.

The implementation of the RFC 8252 specification enables developers to build mobile applications without requiring a proxy server to route redirect calls to their mobile app.

The PKCE extension provides a technique for public clients to mitigate the threat of a “man-in-the-middle” attack. This involves creating a secret that is used when exchanging the authorization code to obtain an access token.

PKCE uses a code challenge that is derived from a code-verifier. The standard supports two styles of code challenge:

  • plain
  • S256

However, the Blue Button 2.0 API only supports the “S256” style code challenge.

Where the:

codechallenge = BASE64URL-ENCODE(SHA256(ASCII(codeverifier)))

The following additional parameters and values are sent as part of the OAuth2.0 Authorization Request:

- code_challenge
- codechallengemethod = "S256"

More details can be found about this flow on OAuth.com. Check out this link: Protecting Mobile Apps with PKCE - OAuth 2.0 Servers

Registering Your App for Mobile App Support

When you register your application in the Blue Button 2.0 API Developer Sandbox, you will want to specify a unique custom URI scheme. This should be a unique value that will not conflict with other custom URI schemes implemented on a user's mobile device.

We recommend that you define your custom URI scheme using a reverse domain name notation. As we developed our own testing application, we implemented a custom URI scheme of:

- gov.cms.bluebutton.oauthtester

This equated to an oauthtester subdomain for the bluebutton.cms.gov domain.

The reverse DNS style custom URI scheme should then be coupled with the re-direct path on the mobile device that will handle the call back from the Blue Button 2.0 API.

For example:

tld.app.subdomain[.subsubdomain]:/callback/path/endpoint

Redirect_URI

When creating an Application in the sandbox a redirect URI is required. This is the API endpoint on your system that receives the callback from the Blue Button 2.0 API after a beneficiary is passed to the Blue Button 2.0 API to authorize your application.

Multiple redirect URIs can be entered in the Redirect_URI field. Each entry should be separated by a space or newline.

A Redirect_URI follows this format:

URLprotocol://[sub-domain.]domain_name[:port]/path

URL Protocol

Three URL protocols are supported, depending on the purpose:

  • http:// protocol
  • https:// protocol
  • custom_url:// protocol

http:// protocol

(Works in: Sandbox only)

The http:// format is only accepted in the sandbox environment. It is typically used by developers for local testing by using http://localhost/ however, any domain name can be used.

https://protocol

(Works in: Sandbox Production)

The https:// format is used for secure communication and is required for all applications in the production environment unless the application is using the Mobile OAuth method for handling callbacks.

custom_url:// protocol

(Works in: Sandbox Production)

The custom_url protocol is used by mobile applications to handle communications directly with your application on a mobile device.

If you are using Mobile OAuth support for communication directly with a mobile device the custom_url should follow this format:

Top-level.domain(TLD).domain-name[.sub-domain][.app_name]

For example, if the Blue Button 2.0 API team created an application we might create a custom_url of:

gov.cms.bluebutton.oauthtester

This would then be incorporated into a redirect URI entry. Here is an example:

gov.cms.bluebutton.oauthtester:8080//bluebutton_app/callback.html

Web Application Flow

To use this flow your application should be registered with Client Type set to confidential and Grant Type set to authorization-code.

Request authorization from user

To allow a user to authorize your application, direct them to the Blue Button 2.0 API authorize endpoint. The request must include the response_type set to code, your application's client_id, and your application's redirect_uri. An optional state field that your application can use to identify the authorization request is recommended.

API version Request URL
v1 https://sandbox.bluebutton.cms.gov/v1/o/authorize/?client_id=swBu7LWsCnIRfu530qnfPw1y5vMmER3lAM2L6rq2&redirect_uri=http://localhost:8080/testclient/callback&response_type=code&state=8e896a59f0744a8e93bf2f1f13230be5
v2 https://sandbox.bluebutton.cms.gov/v2/o/authorize/?client_id=swBu7LWsCnIRfu530qnfPw1y5vMmER3lAM2L6rq2&redirect_uri=&response_type=code&state=8e896a59f0744a8e93bf2f1f13230be5

Exchange code for token

After visiting the authorization page a user will be redirected back to the redirect_uri registered with your application.

For example if the redirect_uri is http://localhost:8080/testclient/callback BlueButton will redirect with this request.

GET http://localhost:8080/testclient/callback?code=TSjqiZCdJwGyytGjz2GzziPfHTJ6z2&state=8e896a59f0744a8e93bf2f1f13230be5

Your application can now exchange the code provided in the redirected request for a full token. Send a POST request to the BlueButton token endpoint providing the code, the application's client_id, client_secret, and redirect_uri. Your request must also specify the grant_type which should always be authorization_code for this flow.

API version Request URL
v1 curl -X POST “https://sandbox.bluebutton.cms.gov/v1/o/token/” \ -u “swBu7LWsCnIRfu530qnfPw1y5vMmER3lAM2L6rq2:\<client_secret\>” \ -d “code=TSjqiZCdJwGyytGjz2GzziPfHTJ6z2&grant_type=authorization_code&redirect_uri=http://localhost/testclient/callback”
v2 curl -X POST “https://sandbox.bluebutton.cms.gov/v2/o/token/” \ -u “swBu7LWsCnIRfu530qnfPw1y5vMmER3lAM2L6rq2:\<client_secret\>” \ -d “code=TSjqiZCdJwGyytGjz2GzziPfHTJ6z2&grant_type=authorization_code&redirect_uri=http://localhost/testclient/callback”

Response

{

"access_token": "oQlduHNr09GKCU506GOgp8OarrAy2q",

"expires_in": 16768.523842,

"token_type": "Bearer",

"scope": "profile patient/Patient.read patient/ExplanationOfBenefit.read patient/Coverage.read"

"refresh_token": "wDimPGoA8vwXP51kie71vpsy9l17HN"

}

Adding the STATE parameter

Client Application Flow

To use this flow your application should be registered with Client Type set to public and Grant Type set to implicit.

Request authorization from user

To use the client application flow direct the user to the Blue Button 2.0 API authorization endpoint with the response_type parameter set to token.

API version Request URL
v1 https://sandbox.bluebutton.cms.gov/v1/o/authorize/?client_id=swBu7LWsCnIRfu530qnfPw1y5vMmER3lAM2L6rq2&redirect_uri=http://localhost:8080/testclient/callback&response_type=token&state=8e896a59f0744a8e93bf2f1f13230be5
v2 https://sandbox.bluebutton.cms.gov/v2/o/authorize/?client_id=swBu7LWsCnIRfu530qnfPw1y5vMmER3lAM2L6rq2&redirect_uri=http://localhost:8080/testclient/callback&response_type=token&state=8e896a59f0744a8e93bf2f1f13230be5

If the user authorizes your application they will be redirected back to the redirect_uri of your application. The request will include an access token in the fragment.

Typescript Example

http://localhost:8080/testclient/callback#access_token=KCHMTX5VHNAXYGYv38eG2RLAX4hL6R&amp;expires_in=35849.875807&amp;token_type=Bearer&amp;scope=profile+patient%2FPatient.read+patient%2FExplanationOfBenefit.read+patient%2FCoverage.read&amp;state=8e896a59f0744a8e93bf2f1f13230be5

You can use this sample account to test your Blue Button 2.0 API OAuth implementation. This account mimics a valid Medicare account but has reduced functionality. For example, you cannot test “Forgot Password” flow.

Jane Doe

Username: BBUser29999

Password: PW29999!


Core Resources

Base Request URL:

https://sandbox.bluebutton.cms.gov

FHIR Resources:

  • Explanation of Benefit
  • Patient
  • Coverage

UserInfo:

  • Get User Profile from an Authorization Token

As a security measure, the beneficiary's date of birth, SSN, and HICN will not be provided by the CMS Blue Button 2.0 API.

We use FHIR Extensions in our API responses.

Explanation of Benefit FHIR Resource

API version Request
v1 HTTP GET /v1/fhir/ExplanationOfBenefit/?patient=[fhir_id]
v2 HTTP GET /v2/fhir/ExplanationOfBenefit/?patient=[fhir_id]

The above URL returns all of the beneficiary's Explanation of Benefit (sometimes referred to as an episode of care) records as an ExplanationOfBenefit FHIR Resource. The bulk of a beneficiary's data is contained within these ExplanationOfBenefit FHIR resources.

Each one can be thousands of lines long.

API version CURL command
v1 curl –header “Authorization: Bearer AUTHORIZATION TOKEN” “https://sandbox.bluebutton.cms.gov/v1/fhir/ExplanationOfBenefit/?patient=-20140000008325”
v2 curl –header “Authorization: Bearer AUTHORIZATION TOKEN” “https://sandbox.bluebutton.cms.gov/v2/fhir/ExplanationOfBenefit/?patient=-20140000008325”

That API call will return an Explanation of Benefit that contains many FHIR resources and is typically thousands of lines long.

Learn more about the Explanation of Benefits FHIR resource in the Blue Button 2.0 API

Response for v1, e.g. :

{

"fullUrl": "https://sandbox.bluebutton.cms.gov/v1/fhir/ExplanationOfBenefit/carrier-22011027731",

"resource": {

"resourceType": "ExplanationOfBenefit",

"id": "carrier-22011027731",

"contained": [

{

"resourceType": "ReferralRequest",

"id": "1",

"status": "completed",

"subject": {

"reference": "Patient/-20140000008325"

},

"requester": {

"agent": {

"identifier": {

"system": "http://hl7.org/fhir/sid/us-npi",

"value": "999999999999"

}

}

},

"recipient": [

{

"identifier": {

"system": "http://hl7.org/fhir/sid/us-npi",

"value": "999999999999"

}

}

]

}

]

…this is only a subset of the entire output…

Patient FHIR Resource

API version Request
v1 HTTP GET /v1/fhir/Patient/[fhir_id]
v2 HTTP GET /v2/fhir/Patient/[fhir_id]

The above URL returns the beneficiary's demographics and other administrative information as a Patient FHIR Resource. This information is mostly contact information, not medical data.

API version CURL command
v1 curl –header “Authorization: Bearer AUTHORIZATION TOKEN” “https://sandbox.bluebutton.cms.gov/v1/fhir/Patient/-20140000008325”
v2 curl –header “Authorization: Bearer AUTHORIZATION TOKEN” “https://sandbox.bluebutton.cms.gov/v2/fhir/Patient/-20140000008325”
Response for v1 e.g.:

{

"resourceType": "Patient",

"id": "-20140000008325",

"extension": [

{

"url": "https://bluebutton.cms.gov/resources/variables/race",

"valueCoding": {

"system": "https://bluebutton.cms.gov/resources/variables/race",

"code": "1",

"display": "White"

}

}

],

"identifier": [

{

"system": "http://bluebutton.cms.hhs.gov/identifier#bene_id",

"value": "-20140000008325"

},

{

"system": "http://bluebutton.cms.hhs.gov/identifier#hicnHash",

"value": "2025fbc612a884853f0c245e686780bf748e5652360ecd7430575491f4e018c5"

}

],

"name": [

{

"use": "usual",

"family": "Doe",

"given": [

"Jane",

"X"

]

}

],

"gender": "unknown",

"birthDate": "2014-06-01",

"address": [

{

"district": "999",

"state": "15",

"postalCode": "99999"

}

]

}

Download a sample Patient FHIR Resource

Coverage FHIR Resource

API version Request
v1 HTTP GET /v1/fhir/Coverage/?beneficiary=[fhir_id]
v2 HTTP GET /v2/fhir/Coverage/?beneficiary=[fhir_id]

The above URL returns the beneficiary's Coverage information as an Coverage FHIR Resource.

API version CURL command
v1 curl –header “Authorization: Bearer AUTHORIZATION TOKEN” “https://sandbox.bluebutton.cms.gov/v1/fhir/Coverage/?beneficiary=-20140000008325”
v2 curl –header “Authorization: Bearer AUTHORIZATION TOKEN” “https://sandbox.bluebutton.cms.gov/v2/fhir/Coverage/?beneficiary=-20140000008325”

Response for v1 e.g.:

{

"fullUrl": "https://sandbox.bluebutton.cms.gov/v1/fhir/Coverage/part-a-20140000008325",

"resource": {

"resourceType": "Coverage",

"id": "part-a-20140000008325",

"extension": [

{

"url": "https://bluebutton.cms.gov/resources/variables/ms_cd",

"valueCoding": {

"system": "https://bluebutton.cms.gov/resources/variables/ms_cd",

"code": "10",

"display": "Aged without end-stage renal disease (ESRD)"

}

},

{

"url": "https://bluebutton.cms.gov/resources/variables/orec",

"valueCoding": {

"system": "https://bluebutton.cms.gov/resources/variables/orec",

"code": "0",

"display": "Old age and survivor&#39;s insurance (OASI)"

}

},

{

"url": "https://bluebutton.cms.gov/resources/variables/esrd_ind",

"valueCoding": {

"system": "https://bluebutton.cms.gov/resources/variables/esrd_ind",

"code": "0",

"display": "the beneficiary does not have ESRD"

}

},

{

"url": "https://bluebutton.cms.gov/resources/variables/a_trm_cd",

"valueCoding": {

"system": "https://bluebutton.cms.gov/resources/variables/a_trm_cd",

"code": "0",

"display": "Not Terminated"

}

}

]

…this is only a subset of the entire output…

Compress Resources for more efficient data transfers

To improve the performance when transferring large data resources it is possible to turn on compression. Gzip compression is turned off by default. Compression can be activated for the following content types:

  • text/html
  • text/plain
  • application/json
  • application/fhir+json

To activate compression add the following to the header:

Accept-Encoding: gzip

The minimum payload size we will gzip is 1 kilobyte. If the original uncompressed size of the payload is less than 1 kb, we will not apply gzip compression to our response. Therefore, developers should ensure their applications handle this scenario gracefully by checking for the Content-Encoding: gzip response header before trying to decompress.

Download a sample Coverage FHIR Resource

Get User Profile for an Authorization Token

HTTP GET /connect/userinfo

The UserInfo Endpoint is an OAuth 2.0 Protected Resource.The above URL fetches the fictitious beneficiary's basic account information given an Authorization Token. This is most often used when creating an account within your application. An HTTP GET is called and the response is returned as JSON.

API version CURL command
v1 curl –header “Authorization: Bearer AUTHORIZATION TOKEN” “https://sandbox.bluebutton.cms.gov/v1/connect/userinfo”
v2 curl –header “Authorization: Bearer AUTHORIZATION TOKEN” “https://sandbox.bluebutton.cms.gov/v2/connect/userinfo”

Response:

{

"sub": "fflinstone",

"prefered_username": "fflinstone",

"given_name": "Fred",

"family_name:, "Flinstone,

"name": "Fred Flinstone",

"email": "pebbles-daddy@example.com",

"created": "2017-11-28",

"patient": "123456789",

}

More Efficient Data Queries

Query by Type

Many developers are interested in specific claim types, such as Prescription Drug Events (PDE). The query by type feature will allow applications to request just those claims. This will enable applications to process and download data more quickly and efficiently.

ExplanationOfBenefit resources fall into 8 types:

  • Carrier Claims (CARRIER)
  • Durable Medical Equipment (DME)
  • Home Health Agency Claims (HHA)
  • Hospice Claims (HOSPICE)
  • Inpatient Claims (INPATIENT)
  • Outpatient Claims (OUTPATIENT)
  • Part D Events (PDE)
  • Skilled Nursing Facility Claims (SNF)

By default, the FHIR API returns all of these claim types when requesting the EOB for a beneficiary. You can use the Type query parameter to request specific claim types.

For example, to request only Part D drug claims, add the query parameter:

?type=pde

To request multiple claim types, a list of comma-separated values can be given for the TYPE parameter.

If multiple codes are specified, EOBs matching all of those claim types will be returned:

API version Request URL
v1 /v1/fhir/ExplanationOfBenefit?patient=123&type=carrier,dme,hha,hospice,inpatient,outpatient,snf
v2 /v2/fhir/ExplanationOfBenefit?patient=123&type=carrier,dme,hha,hospice,inpatient,outpatient,snf

The full list of claim types are:

carrier

https://bluebutton.cms.gov/resources/codesystem/eob-type carrier

pde

https://bluebutton.cms.gov/resources/codesystem/eob-type pde

dme

https://bluebutton.cms.gov/resources/codesystem/eob-type dme

hha

https://bluebutton.cms.gov/resources/codesystem/eob-type hha

hospice

https://bluebutton.cms.gov/resources/codesystem/eob-type hospice'

inpatient

https://bluebutton.cms.gov/resources/codesystem/eob-type inpatient'

outpatient

https://bluebutton.cms.gov/resources/codesystem/eob-type outpatient'

snf

https://bluebutton.cms.gov/resources/codesystem/eob-type snf

It is important to use lower case when requesting a claim type. If you submit an invalid combination of claim types or use the wrong case you'll see a message like this:

{

"detail": "not a valid value"

}

The status code for this message is a 400 Bad Request.

Query by Type Examples:

In the sandbox there are synthetic beneficiaries with three of the eight claim types:

  • carrier
  • inpatient
  • pde

Let us take a synthetic beneficiary record:

Username: BBUser20023

Password PW20023!

The FHIR ID for this beneficiary is -20140000000024

Let us do a regular ExplanationOfBenefit request:

API version Request
v1 https://sandbox.bluebutton.cms.gov/v1/fhir/ExplanationOfBenefit/
v2 https://sandbox.bluebutton.cms.gov/v2/fhir/ExplanationOfBenefit/

This bundle identifies 148 claims, returning the first 10. Here is how the start of the bundle will look:

Response for v1, e.g.:

{

"resourceType": "Bundle",

"id": "9562c9b7-df79-419a-a94b-ef8cc9347e0e",

"meta": {

"lastUpdated": "2019-11-05T22:05:48.257-05:00"

},

"type": "searchset",

"total": 148,

"link": [

{

"relation": "first",

"Url": "https://sandbox.bluebutton.cms.gov/v1/fhir/ExplanationOfBenefit?_count=10&amp;startIndex=0&amp;patient=-20140000000024"

},

There are three claim types in this beneficiary's record:

  • Carrier (44)
  • Inpatient (1)
  • PDE (103)

The queries to request each claim type individually would be:

Carrier Claims

API version Request
v1 https://sandbox.bluebutton.cms.gov/v1/fhir/ExplanationOfBenefit/?type=carrier
Or
https://sandbox.bluebutton.cms.gov/v1/fhir/ExplanationOfBenefit/?type=https://bluebutton.cms.gov/resources/codesystem/eob-type|carrier
v2 https://sandbox.bluebutton.cms.gov/v2/fhir/ExplanationOfBenefit/?type=carrier
Or
https://sandbox.bluebutton.cms.gov/v2/fhir/ExplanationOfBenefit/?type=https://bluebutton.cms.gov/resources/codesystem/eob-type|carrier

Inpatient Claims

API version Request
v1 https://sandbox.bluebutton.cms.gov/v1/fhir/ExplanationOfBenefit/?type=inpatient
Or
https://sandbox.bluebutton.cms.gov/v1/fhir/ExplanationOfBenefit/?type=https://bluebutton.cms.gov/resources/codesystem/eob-type|inpatient
v2 https://sandbox.bluebutton.cms.gov/v2/fhir/ExplanationOfBenefit/?type=inpatient
Or
https://sandbox.bluebutton.cms.gov/v2/fhir/ExplanationOfBenefit/?type=https://bluebutton.cms.gov/resources/codesystem/eob-type|inpatient

PDE Claims Since many of our developers are interested in the Part D drug claims it is now possible to query for only PDE-type claims.

API verion Request
v1 https://sandbox.bluebutton.cms.gov/v1/fhir/ExplanationOfBenefit/?type=pde
Or
https://sandbox.bluebutton.cms.gov/v1/fhir/ExplanationOfBenefit/?type=https://bluebutton.cms.gov/resources/codesystem/eob-type|pde
v2 https://sandbox.bluebutton.cms.gov/v2/fhir/ExplanationOfBenefit/?type=pde
Or
https://sandbox.bluebutton.cms.gov/v2/fhir/ExplanationOfBenefit/?type=https://bluebutton.cms.gov/resources/codesystem/eob-type|pde

Query by “lastUpdated” Field

The HL7 FHIR specification provides a Meta section in each resource. The lastUpdated field represents the date and time of the last update. This takes the format of an “instant” type:

YYYY-MM-DDThh:mm:ss.sss+zz:zz.

The HL7 FHIR specification also provides a _lastUpdated query parameter for the search operations on the end-points. By using the _lastUpdated query parameter, an application will be able to request only the records that have changed before or after a specific date. If you keep track of the date of a previous request, you can request just the changes since your previous request. The format of this request would be:

for v1: https://sandbox.bluebutton.cms.gov/v1/fhir/Patient?_id=-19990000000001&amp;_lastUpdated=gt2020-02-13T08:00:00-05:00&amp;_format=application%2Fjson%2Bfhir&#39;

for v2: https://sandbox.bluebutton.cms.gov/v2/fhir/Patient?_id=-19990000000001&amp;_lastUpdated=gt2020-02-13T08:00:00-05:00&amp;_format=application%2Fjson%2Bfhir&#39;

Note:

Do not input dates before 2020-02-12 with _lastUpdated. Limitations of our backend service prevent data before 2020-02-12 from being tagged correctly.

The output from that request would look like this:

API version Request URL
v1 /v1/fhir/Patient?_id=-19990000000001&amp;_lastUpdated=gt2020-02-13T08:00:00-05:00&amp;_format=application%2Fjson%2Bfhir&#39;
v2 /v2/fhir/Patient?_id=-19990000000001&amp;_lastUpdated=gt2020-02-13T08:00:00-05:00&amp;_format=application%2Fjson%2Bfhir&#39;

Response for v1, e.g.:

{

"resourceType": "Bundle",

"id": "7d8ff6a1-95f9-4210-b08b-58a96ea74494",

"meta": {

"lastUpdated": "2020-02-14T08:57:16.641-05:00"

},

"type": "searchset",

"total": 1,

"link": [

{

"relation": "self",

"url": "https://prod-sbx.bfdcloud.net/v1/fhir/Patient?_format=application%2Fjson%2Bfhir&amp;_id=-19990000000001&amp;_lastUpdated=gt2020-02-13T08%3A00%3A00-05%3A00"

}

],

"entry": [

{

"resource": {

"resourceType": "Patient",

"id": "-19990000000001",

"meta": {

"lastUpdated": "2020-02-13T21:53:06.017-05:00"

},

The BB2.0 API supports operators for less than (lt), greater than (gt), less than or equal (le), and greater than or equal (ge) the specified instant. It is also possible to specify a time interval by using two _lastUpdated parameters like this:

API version Request URL
v1 /v1/fhir/ExplanationOfBenefit?patient=Patient/-19990000000001&amp;_lastUpdated=gt2020-02-13T08:00:00-05:00&amp;_lastUpdated=lt2020-02-14T08:00:00-05:00&amp;_format=application%2Fjson%2Bfhir
v2 /v2/fhir/ExplanationOfBenefit?patient=Patient/-19990000000001&amp;_lastUpdated=gt2020-02-13T08:00:00-05:00&amp;_lastUpdated=lt2020-02-14T08:00:00-05:00&amp;_format=application%2Fjson%2Bfhir

FHIR Data Model

We have mapped over 1,300 fields from the CMS Chronic Conditions Data Warehouse (CCW) into FHIR. These fields are surfaced across the Patient, Coverage and Explanation of Benefits FHIR resources.

  • Beneficiary Enrollment Record
  • Carrier Claims (CARRIER)
  • Durable Medical Equipment (DME)
  • Home Health Agency Claims (HHA)
  • Hospice Claims (HOSPICE)
  • Inpatient Claims (INPATIENT)
  • Outpatient Claims (OUTPATIENT)
  • Part D Events (PDE)
  • Skilled Nursing Facility Claims (SNF)

The Blue Button 2.0 API FHIR data model leverages coding systems specific to Medicare billing forms and/or the Chronic Conditions Warehouse, FHIR and Industry Coding Systems.

For Example:

View the full list of Blue Button 2.0 API FHIR Data Model Coding Systems and Identifiers

How Often Will New/Updated Data Be Available?

Medicare Part A, B, and D claims data will be refreshed weekly.

Our schedules may vary depending on many things like maintenance, delayed delivery of claims to the CCW data warehouse, or additional data quality processing that's needed.

We recommend you have a daily job to fetch new claims data for your users. Please be responsible with your API usage and comply with the Service Management Rights to Limit conditions in the Blue Button 2.0 API Terms of Service.

Synthetic Data

The CMS Blue Button 2.0 API offers a synthetic data set for developers to test against. This means that each request returns a realistic value. For example, if a patient is prescribed the diabetes medication Metformin, the associated cost and date of this prescription will be accurate.

Please note that this synthetic data set does not represent a longitudinal patient view. The claims—though representative independently—are shuffled and randomly assigned to patients. To build the synthetic data set, we selected a number of random claims, and shuffled them like a deck of cards among a group of fictitious Patient IDs. This will allow developers to test the Blue Button 2.0 API system, but could result in a patient with records for contradictory procedures.

Production Data

The CMS Blue Button 2.0 API has at least one claim for over 60M beneficiaries.

Today, there are approximately 38M beneficiaries in traditional or fee-for-service Medicare. The Blue Button 2.0 API has Part A/B/D data for those beneficiaries plus Part D data for some beneficiaries on Medicare Advantage plans.

Part D has always been a separate program, but certain plans include both the MA benefits (Part C) and Part D. As a result, Part D drug event data is collected separately from MA encounter data. Part D drug event data for all participants in Part D has been collected by the agency since the program began in the mid-2000s.

The API also has historical claims data going back four years. All of these factors contribute to the 53M number we use to describe the total number of beneficiaries available via the Blue Button 2.0 API.


Sample Beneficiaries

CSV of sample beneficiaries with rich claims data

When getting started with the Blue Button 2.0 API, it can be overwhelming to understand all of the coding systems and types of data that can be found in the Explanation of Benefit FHIR resource.

We have provided some hypothetical Beneficiaries to help give you a sense of what is found in Medicare Claims data.

Meet Lucille

Lucille is a 70-year old female. She has non-small cell lung cancer. Prior to her diagnosis, Lucille was active and had no significant health issues. She went on daily walks around her neighborhood, did yoga and made a concerted effort to eat healthy. Lucille smoked cigarettes for a few years when she was a teenager, but she quit after her father passed away from lung cancer. Her only other family history is mild hypertension on her mother’s side.

Below are some examples you may find in the Explanation of Benefit FHIR resource for Lucille.

Office Visit

"service": {

"coding": [{

"system": "https://www.cms.gov/Medicare/Coding/MedHCPCSGenInfo/index.html",

"version": "0",

"code": "99215"

Lung Biopsy

"procedureCodeableConcept": {

"coding": [{

"system": "http://hl7.org/fhir/sid/icd-9-cm",

"code": "3328"

Diagnostic Radiology

"service": {

"coding": [{

"system": "https://www.cms.gov/Medicare/Coding/MedHCPCSGenInfo/index.html",

"version": "0",

"code": "70553"

Radiation Therapy

"service": {

"coding": [{

"system": "https://www.cms.gov/Medicare/Coding/MedHCPCSGenInfo/index.html",

"version": "9",

"code": "77263"

Chemo

"service": {

"coding": [{

"system": "https://www.cms.gov/Medicare/Coding/MedHCPCSGenInfo/index.html",

"version": "0",

"code": "96400"

Meet Jack

Jack is a 70 year-old male with Type 2 Diabetes and high blood pressure. Jack takes daily medication and his Doctor told him he needs to lose weight. He takes Glimepiride to help control his blood sugar and previously was on Metformin.

Learn more about “Jack” (PDF)


Production API Access

In order to gain production access, an organization should start by reviewing the Terms of Service, production access user guide, and checklist. Once an organization believes it is fulfilling all the requirements detailed in the checklist and is adherent to the terms of service, they should email bluebuttonapi@cms.hhs.gov to set up a production access demonstration meeting with the CMS team.


Developer Guidelines

Below are guidelines you should follow to be successful in your Blue Button 2.0 API integration.

Your Privacy Policy

You will be asked to provide a URL to your privacy policy and terms and conditions when registering your app in the Blue Button 2.0 API Developer Portal. These links should be easy to access and understand by a beneficiary using your app. Consider using the Model Privacy Notice.

Rate Limiting and Data Refresh

Medicare Part A, B, and D claims data will be refreshed weekly.

Our schedules may vary depending on many things like maintenance, delayed delivery of claims to the CCW data warehouse, or additional data quality processing that's needed.

We recommend you have a daily or weekly job to fetch new claims data for your users. Please be responsible with your API usage and comply with the Service Management Rights to Limit conditions in the Blue Button 2.0 API Terms of Service.

Use of the Blue Button 2.0 API Logo

The Blue Button 2.0 API logo and usage guidelines is detailed here.

Beneficiary Revokes Access

A beneficiary may revoke access to your application via the Medicare website. When you encounter an invalid token indicating a beneficiary has revoked access, you should make a reasonable attempt to handle that case making it easy for the beneficiary to understand what is happening with their Medicare data.

“Medicare is unable to retrieve your data at this time due to an internal issue. Our team is aware of the issue and is working to resolve it. Please try again at a later time. We apologize for any inconvenience.”

If you or your users encounters this error message, know that our team is aware of the issue and is working to resolve it as quickly as possible.


Blue Button Implementation Guide

The Blue Button 2.0 API team has created a Blue Button 2.0 API Implementation Guide (BB2IG). You can access the guide here: Blue Button 2.0 API Implementation Guide.

The BB2IG features nine profiles in this version of the guide:


Implementation Guides

Questions:

·Are these linked Implementation Guides sufficient for you to start implementing v2?

·If not, what other documentation should Blue Button 2.0 provide?

·HL7 FHIR Common Payer Consumer Data Set (CPCDS)

Implementation Guide: Version 1.0.0, Date 2020-11-23.

·URL:http://hl7.org/fhir/us/carin-bb/

·Summary: This IG describes the CARIN Alliance Blue Button 2.0 Framework and Common Payer Consumer Data Set (CPCDS), providing a set of resources that payers can exchange with third-parties to display to consumers via a FHIR-based API. This IG will help Medicare, Medicaid, CHIP, BHP standard health plans, and QHP issuers on the FFEs share adjudicated claims and encounter data via the Patient Access API discussed in section II.A. of this proposed rule. It includes data elements and coding instructions each impacted payer can use to prepare and share the specified data.

·HL7 FHIR CARIN - v2 Artifacts Summary

Implementation Guide: Version 1.0.0, Date 2020-11-23.

·URL: https://build.fhir.org/ig/HL7/carin-bb/artifacts.html#4

·Summary: The purpose of this IG is to outline the different artifacts released by CARIN for v2. The artifacts contain code explanations and benefits for the different EOB Profiles.

- HL7 FHIR CARIN – BlueButton GitHub IG

  • Github Version 0.1.13, Date 2020-11-23
  • URL: https://github.com/HL7/carin-bb/ Summary: This implementation guide describes the CARIN Blue Button® Framework and Common Payer Consumer Data Set (CPCDS), providing a set of resources that payers can display to consumers via a FHIR API.

STU3 vs FHIR R4 Comparison Tables

See also the version transforms and the note about version specific extensions. (This analysis is available as XML or JSON from HL7 (note: this includes all R4 data).


Additional Information

Migrating to v2/FHIR R4 FAQ

Join the Google Groups for any APIs you access for the most up to date information:


Back to top