Skip to main content

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.

API Documentation

Beneficiary Claims Data API (BCDA) uses Bulk Fast Healthcare Interoperability Resources (FHIR) to share claims data. You can use a variety of tools or client software programs to access the sandbox and production environments.

Getting started

  1. Learn about BCDA

    Explore the documentation, Data Dictionary, and sample files.

  2. 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.

  3. Get production access

    Eligible model entities must have production credentials to access their enrollees' claims data.

Endpoints

Endpoints request data by resource type. Data is returned for enrollees attributed to your organization, but you can’t make requests for individual patient data.

/metadata

Request the FHIR CapabilityStatement for basic information on the API, like its version and whether it’s currently active. This does not require authorization.

/Group

Use the /Group endpoint to request the ExplanationOfBenefit, Patient, and Coverage resource types. For partially adjudicated claims, this includes Claim and ClaimResponse. Provide the all or runout identifier to indicate whose data you’d like returned:

  • /Group/all: returns data for all Medicare enrollees currently attributed to your model entity
  • /Group/runout: returns data for Medicare enrollees attributed to your model entity during the previous year, but not the current year. The data will have a service date no later than December 31 of the previous year.

Using the _since parameter with /Group will return resources updated after the date provided for existing enrollees and all resources for newly attributed enrollees.

This lets you retrieve all new claims data with a single request. If you don’t apply _since, BCDA will return data as early as 2014.

/Patient

Similar to /Group/all, use the /Patient endpoint to request data for all Medicare enrollees currently attributed to your model entity.

Using the _since parameter with /Patient will return resources updated after the date provided for existing and newly attributed enrollees.

Newly attributed enrollees are those who’ve been assigned to your model entity since your last attribution date. If you don’t apply _since, BCDA will return data as early as 2014.

/jobs

Request information about previous job requests, including the job ID, creation time, completion time, and original job request.

If you can’t remember the job ID after starting a job, use this endpoint to retrieve the ID. Each entry in the resource bundle is in the FHIR Task format.

/attribution_status

Request a datetime and timestamp for when your enrollee list or runout files were last updated.

Attribution files are updated once per month. It can be useful to retrieve all claims data for newly attributed enrollees to get a full picture of their health histories.

Parameters

Use parameters during job requests to filter or specify the resources returned:

  • The _type parameter: Limit your request to specific resource types. Instead of receiving data from all available resource types, specify 1 or more.

  • The _since parameter: Apply a date boundary to your requests. Instead of receiving the full record of historical data, filter for resources last updated after a specified date.

Explore how to filter claims data

Additional resources

BCDA provides Medicare claims data using the NDJSON format.

cms.gov

official website of the U.S. Department of Health and Human Services and the Centers for Medicare & Medicaid Services.

Looking for U.S. government information and services?
Visit USA.gov