API Documentation
The AB2D API uses Fast Healthcare Interoperability Resources (FHIR) to share enrollees’ Medicare Parts A and B claims data. Only active, stand-alone Prescription Drug Plan (PDP) sponsors are eligible to use AB2D. You can use a variety of tools or client software programs, like curl, to access the sandbox and production environments.
Getting started
-
Learn about AB2D
Explore the documentation, Data Dictionary, and sample files.
-
Use the sandbox
The sandbox environment allows anyone to try the API and download test claims data. Learn how to get a bearer token and access the sandbox.
-
Get production access
PDP sponsors must have production access to access their enrollees’ claims data.
What’s the difference between the sandbox and production environments?
| Sandbox | Production |
|---|---|
| Available to everyone | Must have completed the steps for production access |
| Contains synthetic claims data | Contains real Medicare enrollee data |
The sandbox environment
The sandbox (sandbox.ab2d.cms.gov) is a public environment available to anyone who wants to learn how the API works. AB2D provides you with test credentials for access to sandbox data. You’ll use the sandbox identity provider (test.idm.idp.cms.gov) for this.
The production environment
Production (api.ab2d.cms.gov) is a private environment available only to PDP sponsors who have completed the steps to gain production access. You’ll need to provide the static IP address(es) for each system using the API. AB2D then provides you with production credentials for access to your enrollees’ data. You’ll use the production identity provider (idp.cms.gov) for this.
Both environments use the same endpoints with the main differences being the credentials used for your bearer token and the environment URL.
Expected workflow
Jobs are units of work that export and compile Medicare claims data. They are broken into 4 steps. These phases are standard regardless of your programming language or platform. The AB2D workflow is based on the Bulk Data Implementation Guide.
| Step | Goal | Endpoint | Time | Frequency |
|---|---|---|---|---|
| Get a bearer token | Get a token for authentication with the AB2D API. | Learn how to get a bearer token. | Seconds | At least every hour during the job. |
| Start a job | Start a job and save the unique job ID. | Export endpoint | Seconds | Once a job |
| Check job status | Check on the job status as you wait for it to finish. | Status endpoint | Minutes to hours depending on contract size | Once every few minutes |
| Download the files | Download the files returned from a completed job. | Download endpoint | Minutes to hours depending on download speeds | Once a job |
| Optional - Check the health of the AB2D API | Check the current status of the API, like whether it’s up, down, or busy. | Health endpoint | Seconds | Once a job |
Endpoints, schemas, and parameters
Get an overview of the endpoints you can request at the sandbox or production URL. You can also visit the AB2D Swagger UI, which is based on the OpenAPI specification. While starting a job, you can use parameters to filter or specify the claims data returned.
JSON resources
Both versions of AB2D use the JSON (NDJSON) data format for the FHIR ExplanationOfBenefit resource type.
Glossary
Bearer tokens, also referred to as access tokens or JSON web tokens, are used during the OAuth 2.0 authentication and authorization process. You need a bearer token every time you access the sandbox or production environment.
You can get a bearer token by providing Okta with sandbox credentials or the production credentials received during production access. Bearer tokens expire after an hour, after which you must complete the process again.
