CMS Blue Button® API
The Centers for Medicare and Medicaid Services (CMS) Blue Button API enables Medicare Beneficiaries to connect their Medicare claims data to the applications, services, and research programs they trust.
The CMS Blue Button API:
- Enables a Developer to register a Beneficiary-facing application
- Enables a Beneficiary to grant an application access to four years of their Part A, B, and D claims data
- Uses the HL7 FHIR standard for Beneficiary data and the OAuth 2.0 standard for Beneficiary authorization
Join the Developer Preview
CMS is inviting Developers to provide feedback on the new CMS Blue Button API for the purpose of improved development.
Sign Up for the Developer Preview
Participants in the Developer Preview can build integrations with their software using synthetic claims data.
Try the API
During the Developer Preview, you will be able to query a sandbox environment populated with synthetic Beneficiary claims data.
Here's what you can do:
- Retrieve a Patient by ID
- Retrieve all Explanation of Benefit records for a Patient by ID
- Retrieve Patient coverage by ID
To join the Developer Preview, register a sample application and retrieve synthetic data for a sample Patient ID by calling the API, follow these four steps:
Step 1: Join the Developer Preview and register a sample application
- Join the Developer Preview to access the Developer Dashboard
- Click "Application Registration" to register a new sample application and get a Client ID and Secret
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.
You can generate an access token for synthetic Patient 20140000008325 and sample Application TestApp by following these steps:
- Login to the Developer Portal
- Click on Test Client to begin
- Click "sample Authorization flow"
- Click the link to authorize. This will start the authorization flow to TestApp
- Login to your Blue Button Developer Preview Account (click here if you need to Join the Developer Preview)
- Agree to the Personal Health Information Sharing disclaimer (sample)
- Review the permissions TestApp is asking for and approve (sample)
- You will see a JSON document containing your access token and other information
You can now use your access token wherever "YOUR TOKEN HERE" is referenced below.
Step 3: Call the API
curl --header "Authorization: Bearer YOUR TOKEN HERE" https://sandbox.bluebutton.cms.gov/v1/fhir/Patient/20140000008325Or, try this out in Postman:
- From Postman, open a new tab
- Paste the Request URL: https://sandbox.bluebutton.cms.gov/v1/fhir/Patient/20140000008325
- Click "Authorization", select type "Bearer Token" and paste your token in the Token field
- Click "Preview Request" and see a success message "Request headers were successfully updated with authorization data for preview."
- Click "Send" and see the synthetic Beneficiary's personal health information as a Patient FHIR Resource display under "Body" in Postman.
Step 4: View the API response
In the API response for Patient 20140000008325 you will find:
- 32 total claims (140 total claim lines)
- 25 carrier claims (110 carrier claim lines)
- 2 inpatient claims (25 inpatient claim lines)
- 5 Part D events
Authorization
Base Request URL:
https://sandbox.bluebutton.cms.govTo use the Blue Button OAuth, you need to go through two separate processes. First, you must create a Developer Preview account and register your application to gain the credentials necessary to request access.
Next, you must develop your application to correctly make requests and handle the responses from both the user's browser and the Blue Button servers.
Below you will find a sample account you can use to test your Blue Button OAuth implementation. This account mimics a valid MyMedicare.gov account but has reduced functionality. For example, you cannot test the "Forgot Password" flow.
Jane Doe Username: User29999 Password: PW29999!
HTTP GET /v1/o/authorize/ HTTP POST /v1/o/token/ Core Resources
Base Request URL:
https://sandbox.bluebutton.cms.govResources:
- Get User Profile from an Authorization Token
- Get all Explanation of Benefit records for an Individual Beneficiary
- Get all Patient Records for an Individual Beneficiary
- Get all Coverage information for an Individual Beneficiary
If the _format option is omitted, then JSON is returned by default.
As a security measure the date of birth, SSN, and HICN will not be provided by the CMS Blue Button API.
We use FHIR Extensions in our API responses.
View Interactive Documentation (Swagger)
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 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.
curl --header "Authorization: Bearer AUTHORIZATION TOKEN" "https://sandbox.bluebutton.cms.gov/v1/connect/userinfo" {
"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",
}Get all Explanation Of Benefit records for an Individual Beneficiary
/v1/protected/bluebutton/fhir/v1/ExplanationOfBenefit/?patient=[fhir_id]The above URL returns all of the synthetic 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.
curl --header "Authorization: Bearer AUTHORIZATION TOKEN" "https://sandbox.bluebutton.cms.gov/v1/fhir/ExplanationOfBenefit/?patient=20140000008325"{
"resourceType": "ExplanationOfBenefit",
"id": "EB3500",
"text": {
"status": "generated",
"div": "A human-readable rendering of the ExplanationOfBenefit"
},
"identifier": [
{
"system": "http://www.BenefitsInc.com/fhir/explanationofbenefit",
"value": "987654321"
}
],
"status": "active",
"type": {
"coding": [
{
"system": "http://hl7.org/fhir/ex-claimtype",
"code": "oral"
}
]
},
"patient": {
"reference": "Patient/pat1"
},
"created": "2014-08-16",
"organization": {
"reference": "Organization/2"
},
"claim": {
"reference": "Claim/100150"
},
"claimResponse": {
"reference": "ClaimResponse/R3500"
},
"outcome": {
"coding": [
{
"system": "http://hl7.org/fhir/remittance-outcome",
"code": "complete"
}
]
},
"disposition": "Claim settled as per contract.",
"careTeam": [
{
"sequence": 1,
"provider": {
"reference": "Practitioner/example"
}
}
],
"insurance": {
"coverage": {
"reference": "Coverage/9876B1"
}
},
"item": [
{
"sequence": 1,
"careTeamLinkId": [
1
],
"service": {
"coding": [
{
"system": "http://hl7.org/fhir/service-uscls",
"code": "1200"
}
]
},
"servicedDate": "2014-08-16",
"unitPrice": {
"value": 135.57,
"system": "urn:iso:std:iso:4217",
"code": "USD"
},
"net": {
"value": 135.57,
"system": "urn:iso:std:iso:4217",
"code": "USD"
},
"adjudication": [
{
"category": {
"coding": [
{
"code": "eligible"
}
]
},
"amount": {
"value": 120.00,
"system": "urn:iso:std:iso:4217",
"code": "USD"
}
},
{
"category": {
"coding": [
{
"code": "eligpercent"
}
]
},
"value": 0.80
},
{
"category": {
"coding": [
{
"code": "benefit"
}
]
},
"amount": {
"value": 96.00,
"system": "urn:iso:std:iso:4217",
"code": "USD"
}
}
]
}
],
"totalCost": {
"value": 135.57,
"system": "urn:iso:std:iso:4217",
"code": "USD"
},
"totalBenefit": {
"value": 96.00,
"system": "urn:iso:std:iso:4217",
"code": "USD"
}
}Get all Patient Records for an Individual Beneficiary
HTTP GET /v1/fhir/Patient/[fhir_id]The above URL returns the synthetic Beneficiary's personal health information as a Patient FHIR Resource. This information is mostly contact information, not medical data.
curl --header "Authorization: Bearer AUTHORIZATION TOKEN" "https://sandbox.bluebutton.cms.gov/v1/fhir/Patient/20140000008325"{
"resourceType": "Patient",
"id": "20140000008325",
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/us-core-race",
"valueCodeableConcept": {
"coding": [
{
"system": "https://www.ccwdata.org/cs/groups/public/documents/datadictionary/race.txt",
"code": "1"
}
]
}
}
],
"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"
}
]
}
Get all Coverage Information for an Individual Beneficiary
/v1/fhir/Coverage/?patient=[fhir_id]The above URL returns the synthetic Beneficiary's coverage information as an ExplanationOfBenefit FHIR Resource.
curl --header "Authorization: Bearer AUTHORIZATION TOKEN" "https://sandbox.bluebutton.cms.gov/v1/fhir/Coverage/?patient=20140000008325"{
"resourceType": "Bundle",
"id": "28d26ab6-2043-4afd-8c9a-835c0ff3e179",
"meta": {
"lastUpdated": "2017-12-20T10:21:08.565-05:00"
},
"type": "searchset",
"total": 3,
"link": [
{
"relation": "self",
"url": "https://sandbox.bluebutton.cms.gov/v1/fhir/Coverage/?_format=application%2Fjson%2Bfhir&beneficiary=Patient%2F20140000008325"
}
],
"entry": [
{
"fullUrl": "https://sandbox.bluebutton.cms.gov/v1/fhir/Coverage/part-a-20140000008325", "resource": {
"resourceType": "Coverage",
"id": "part-a-20140000008325",
"extension": [
{
"url": "https://www.ccwdata.org/cs/groups/public/documents/datadictionary/ms_cd.txt", "valueCodeableConcept": {
"coding": [
{
"system": "https://www.ccwdata.org/cs/groups/public/documents/datadictionary/ms_cd.txt",
"code": "10"
}
]
}
},
{
"url": "https://www.ccwdata.org/cs/groups/public/documents/datadictionary/orec.txt",
"valueCodeableConcept": {
"coding": [
{
"system": "https://www.ccwdata.org/cs/groups/public/documents/datadictionary/orec.txt",
"code": "0"
}
]
}
},
{
"url": "https://www.ccwdata.org/cs/groups/public/documents/datadictionary/crec.txt",
"valueCodeableConcept": {
"coding": [
{
"system": "https://www.ccwdata.org/cs/groups/public/documents/datadictionary/crec.txt",
"code": "0"
}
]
}
},
{
"url": "https://www.ccwdata.org/cs/groups/public/documents/datadictionary/esrd_ind.txt",
"valueCodeableConcept": {
"coding": [
{
"system": "https://www.ccwdata.org/cs/groups/public/documents/datadictionary/esrd_ind.txt",
"code": "0"
}
]
}
}
],
"status": "active",
"type": {
"coding": [
{
"system": "Medicare",
"code": "Part A"
}
]
},
"beneficiary": {
"reference": "Patient?identifier=CCW.BENE_ID|20140000008325"
},
"grouping": {
"subGroup": "Medicare",
"subPlan": "Part A"
}
}
},
{
"fullUrl": "https://sandbox.bluebutton.cms.gov/v1/fhir/Coverage/part-b-20140000008325", "resource": {
"resourceType": "Coverage",
"id": "part-b-20140000008325",
"extension": [
{
"url": "https://www.ccwdata.org/cs/groups/public/documents/datadictionary/ms_cd.txt", "valueCodeableConcept": {
"coding": [
{
"system": "https://www.ccwdata.org/cs/groups/public/documents/datadictionary/ms_cd.txt",
"code": "10"
}
]
}
}
],
"status": "active",
"type": {
"coding": [
{
"system": "Medicare",
"code": "Part B"
}
]
},
"beneficiary": {
"reference": "Patient?identifier=CCW.BENE_ID|20140000008325"
},
"grouping": {
"subGroup": "Medicare",
"subPlan": "Part B"
}
}
},
{
"fullUrl": "https://sandbox.bluebutton.cms.gov/v1/fhir/Coverage/part-d-20140000008325",
"resource": {
"resourceType": "Coverage",
"id": "part-d-20140000008325",
"extension": [
{
"url": "https://www.ccwdata.org/cs/groups/public/documents/datadictionary/ms_cd.txt",
"valueCodeableConcept": {
"coding": [
{
"system": "https://www.ccwdata.org/cs/groups/public/documents/datadictionary/ms_cd.txt",
"code": "10"
}
]
}
}
],
"type": {
"coding": [
{
"system": "Medicare",
"code": "Part D"
}
]
},
"beneficiary": {
"reference": "Patient?identifier=CCW.BENE_ID|20140000008325"
},
"grouping": {
"subGroup": "Medicare",
"subPlan": "Part D"
}
}
}
]
}FHIR Data Model
The Blue Button API FHIR Data Model leverages Coding Systems specific to Medicare billing forms and/or the Chronic Conditions Warehouse, Standard FHIR and Industry Coding Systems.
For Example:
View the full list of Blue Button API FHIR Data Model Coding Systems and Identifiers
Synthetic Data
For testing purposes, the CMS Blue Button API originally used a fake data set. This means that each claim—including its dates, codings, dollar amounts—was not based in reality, and that values were not associated with one another. For example, a claim for an annual checkup could have shown a $5,000 amount with a date of January 2020.
In December 2017, the CMS Blue Button API launched a new synthetic data set for developers to test against. This means that each claim 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 shuffling them like a deck of cards among a group of fictitious Patient IDs. This will allow developers to test the Blue Button API system, but could result in a patient with records for contradictory procedures.
Meet "Jack"
"Jack" is a hypothetical 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.
Support
The CMS Blue Button API Google Group is where you can interact with other Developers to ask questions, find answers, leave feedback, and share experiences using the CMS Blue Button API.