An official website of the United States government
Here's how you know
Official websites use .gov A
.gov website belongs to an official government organization in the United States.
Secure .gov websites use HTTPS A
lock (
) or https:// means you've safely connected to the .gov website. Share sensitive information
only on official, secure websites.
This section provides information on basic and common queries against the Blue Button API. For a complete listing of Blue Button API calls, see our Swagger documentation.
Sandbox vs. Production Environments
Sandbox
Available to everyone via test credentials
Contains test claims data
Base FHIR URL: https://sandbox.bluebutton.cms.gov/v2/fhir/
Base FHIR URL: https://api.bluebutton.cms.gov/v2/fhir/
To find enrollees with varying volumes and types of data, use this CSV of synthetic data. Using the synthetic data, you can break down claims by type (carrier, inpatient, etc.) for each enrollee/user combination. Synthetic data works in both the Sandbox and Production environments.
Querying Resources
A listing of common API calls are shown in the table below. See “Base FHIR URLs” above and substitute for as appropriate.
Returns a bundle of Patient resources with one entry (one patient resource). You can use the resource ID Bundle.entry.resource.id in later queries. For synthetic data, the ID is a negative number.
GET {baseURL}/Patient/{id}
Returns a single Patient resource. Replace {id} with a valid patient resource ID. See /Patient call above.
Explanation of Benefit Resource requests and descriptions
Request
Description
GET {baseURL}/ExplanationOfBenefit
Returns a bundle of Explanation of Benefit resources. The bundle should contain one or more EOBs. You can use the resource ID located at Bundle.entry.resource.id (the explanation of benefit resource ID) in later queries. For synthetic data, the ID is typically formatted as [claimtype]–[number] Example: carrier--10114937820
GET {baseURL}/ExplanationOfBenefit?patient={id}
Replace {id} with patient resource ID. Returns a bundle of Explanation of Benefit resources. The bundle should contain one or more EOBs. You can use the resource ID located at Bundle.entry.resource.id (the explanation of benefit resource ID) in later queries. For synthetic data, the ID is typically formatted as [claimtype]–[number] Example: carrier--10114937820
GET {baseURL}/ExplanationOfBenefit/{id}
Returns a single Explanation of Benefit resources. Replace {id} with a valid EOB resource ID. See /ExplanationOfBenefit call above.
Capability Statement Resource
Capability Statement resource requests and descriptions
Request
Description
GET {baseURL}/metadata
Returns the FHIR capability statement (Example: the FHIR features and operations supported by this server)
User Info Resource
User Info resource requests and descriptions
Request
Description
GET {host}/{version}/connect/userinfo
If the user grants access to access to their personal information, UserInfo returns name, family name and email. If the user denies access to their personal information, UserInfo returns You do not have permission.
