Step 1: Obtain an Access Token

See Authentication and Authorization above.

Step 2: Start a job to acquire data

Requests to start a job

1. GET /api/v1/Patient/$export

2. GET /api/v1/Patient/$export?_type=ExplanationOfBenefit,Patient

3. GET /api/v1/Patient/$export?_type=Patient

Request Headers

Authorization: Bearer {access_token}
Accept: application/fhir+json
Prefer: respond-async

cURL Commands to start a job

1. curl -X GET 'https://api.bcda.cms.gov/api/v1/Patient/$export' \
   	-H "accept: application/fhir+json" \
   	-H "Prefer: respond-async" \
   	-H "Authorization: Bearer {access_token}"

2. curl -X GET 'https://api.bcda.cms.gov/api/v1/Patient/$export?_type=ExplanationOfBenefit,Patient' \
   	-H "accept: application/fhir+json" \
   	-H "Prefer: respond-async" \
   	-H "Authorization: Bearer {access_token}"

3. curl -X GET 'https://api.bcda.cms.gov/api/v1/Patient/$export?_type=Patient' \
   	-H "accept: application/fhir+json" \
   	-H "Prefer: respond-async" \
   	-H "Authorization: Bearer {access_token}"

Response Example: Successful Request

202 Accepted

Response Example: Too Many Requests

429 Too Many Requests

Response Headers

Content-Location: https://api.bcda.cms.gov/api/v1/jobs/42

Start a Job Explanation

This operation will start a data export job. We have provided three example requests and three example cURL statements to start a job for:

1. All three resource types
2. Any two resource types (we use EOB and Patient as an example)
3. Any single resource type (we use Patient as an example)

For all three resource types, a GET request is made to the /Patient endpoint without the _type query parameter. For one or two resource types, the desired resources are set in the _type query parameter. Notice that, for multiple resource types, they must be separated by commas.

Your access token is required and set as a header. Accept and Prefer headers are also required. The dollar sign ('$') before the word "export" in the URL indicates that the endpoint is an action rather than a resource. The format is defined by the FHIR Bulk Data Export spec.

If the request was successful, a 202 Accepted response code will be returned and the response will include a Content-Location header. The value of this header indicates the location to check for job status and outcome. In the example header below, the number 42 in the URL represents the ID of the export job.

If you're already requesting data from one endpoint and try to request data from that endpoint again while the first request is processing, you'll receive a 429 Too Many Requests error.

Step 3: Check the job status

Request to check the job status

GET https://api.bcda.cms.gov/api/v1/jobs/42

Request Headers

Authorization: Bearer {access_token}
Accept: application/fhir+json

cURL Command to check the job status

curl -X GET 'https://api.bcda.cms.gov/api/v1/jobs/42' \
	-H "accept: application/fhir+json" \
	-H "Authorization: Bearer {access_token}"

Response Example: Completed Job

{
  "transactionTime": "2019-12-09T20:44:01.705398Z",
  "request": "https://api.bcda.cms.gov/api/v1/Patient/$export",
  "requiresAccessToken": true,
  "output": [
    {
      "type": "ExplanationOfBenefit",
      "url": "https://api.bcda.cms.gov/data/42/afd22dfa-c239-4063-8882-eb2712f9f638.ndjson"
    },
    {
      "type": "Coverage",
      "url": "https://api.bcda.cms.gov/data/42/f76a0b76-48ed-4033-aad9-d3eec37e7e83.ndjson"
    },
    {
      "type": "Patient",
      "url": "https://api.bcda.cms.gov/data/42/f92dcf16-63a2-448e-a12a-3bf677f966ed.ndjson"
    }
  ],
  "error": [],
  "JobID": 42
}

Response Headers: Incomplete Job

X-Progress: In Progress

Check the Job Status Explanation

This operation will check on the status of a job and return its progress if it has not finished. Notice that the GET request is simply the URL found in the Content-Location header. The Content Location header is found from the previous step (starting a job) within the response section.

Within the response, a 202 Accepted indicates that the job is processing. The response headers will include the X-Progress header. The X-Progress header value will include text indicating the job's status in BCDA's workflow and an estimated progress percentage. For example, X-Progress: In Progress, 80%.

The status will change from 202 Accepted to 200 OK when the export job is complete and the data is ready to be downloaded.

Claims data can be found at the URLs within the output field. The number 42 in the data file URLs is the same job ID from the Content-Location header URL in the previous step. If some of the data cannot be exported due to errors, details of the errors can be found at the URLs in the error field. The errors are provided in an NDJSON file as FHIR OperationOutcome resources.

Step 4: Download the data

Request to download the data

GET https://api.bcda.cms.gov/data/42/afd22dfa-c239-4063-8882-eb2712f9f638.ndjson

Request Headers

Authorization: Bearer {access_token}
Accept-Encoding: gzip

cURL Command to download the data

curl -X GET 'https://api.bcda.cms.gov/data/42/afd22dfa-c239-4063-8882-eb2712f9f638.ndjson' \
	-H "Accept-Encoding: gzip" \
	-H "Authorization: Bearer {access_token}"

Response Example

1. Explanation of Benefit
2. Patient
3. Coverage

Response Headers

Content-Encoding: gzip

Downloading the Data Explanation

This operation will allow you to obtain the exported data. Notice that the request contains the output URL for a job that is complete (200 OK status).

The "Accept-Encoding: gzip" header is optional, but will return a significantly smaller (40X smaller) file with a faster download speed. You will need to uncompress the file after downloading if you supply this header. When downloading multiple files, you can further speed up the process by downloading multiple files concurrently.

The response will be the requested data as FHIR resources in NDJSON format. Each file related to a different resource type will appear separately and labeled as to which resource type it contains. Examples of data from each Resource Type are available in the guide to working with BCDA data.

Step 1: Obtain an Access Token

See Authentication and Authorization above.

Step 2: Start a job

Request to start a job using the _since parameter within the /Patient endpoint

GET /api/v1/Patient/$export?_type=Patient&_since=2020-02-13T08:00:00.000-05:00

Request Headers

Authorization: Bearer {access_token}
Accept: application/fhir+json
Prefer: respond-async

cURL Command using the _since parameter within the /Patient endpoint

curl -X GET 'https://api.bcda.cms.gov/api/v1/Patient/$export?_type=Patient&_since=2020-02-13T08:00:00.000-05:00' \
	-H "Accept: application/fhir+json" \
	-H "Prefer: respond-async" \
	-H "Authorization: Bearer {access_token}"

Response Example: Successful Request

202 Accepted

Response Example: Too Many Requests

429 Too Many Requests

Response Headers

Content-Location: https://api.bcda.cms.gov/api/v1/jobs/42

Start a Job using _since within the /Patient endpoint Explanation

This operation will start a job for data for all beneficiaries since the selected date: February 13, 2020. Notice that we are seeking data from the /Patient endpoint. This request would behave differently if it was made from the /Group endpoint. In the example, we request the Patient resource type. The steps and format would work similarly for other resource types.

You must provide a _since date in the FHIR format. An access token as well as Accept and Prefer headers are required. The dollar sign ($) before the word "export" in the URL indicates that the endpoint is an action rather than a resource. The format is defined by the FHIR Bulk Data Export spec.

If the request was successful, a 202 Accepted response code will be returned and the response will include a Content-Location header. The value of this header indicates the location to check for job status and outcome. In the example header below, the number 48 in the URL represents the ID of the export job.

Step 3: Check the job status

See Step 3: Check the job status in the Request Data section above.

Step 4: Download the data

See Step 4: Download the data in the Request Data section above.

Step 1: Obtain an Access Token

See Authentication and Authorization above.

Step 2: Start a job

Request to Start a job using the _since parameter within the /Group endpoint

GET /api/v1/Group/all/$export?_type=Patient&_since=2020-02-13T08:00:00.000-05:00

Request Headers

Authorization: Bearer {access_token}
Accept: application/fhir+json
Prefer: respond-async

cURL Command using the _since parameter within the /Group endpoint

curl -X GET 'https://api.bcda.cms.gov/api/v1/Group/all/$export?_type=Patient&_since=2020-02-13T08:00:00.000-05:00' \
	-H "Accept: application/fhir+json" \
	-H "Prefer: respond-async" \
	-H "Authorization: Bearer {access_token}"

Response Example: Successful Request

202 Accepted

Response Example: Too Many Requests

429 Too Many Requests

Response Headers

Content-Location: https://api.bcda.cms.gov/api/v1/jobs/42

Start a Job using _since within the /Group endpoint Explanation

This operation will start a job for filtered data for existing beneficiaries since 8PM EST on February 13th, 2020 and all 7 years of historical data for beneficiaries assigned to your organization in the last month. In the example, we request the Patient resource type. The steps and format would work similarly for other resource types.

You must provide the groupID of "all" as well as a _since date in the FHIR format. An access token as well as Accept and Prefer headers are required. The dollar sign ($) before the word "export" in the URL indicates that the endpoint is an action rather than a resource. The format is defined by the FHIR Bulk Data Export spec.

If the request was successful, a 202 Accepted response code will be returned and the response will include a Content-Location header. The value of this header indicates the location to check for job status and outcome. In the example header below, the number 48 in the URL represents the ID of the export job.

Step 3: Check the job status

See Step 3: Check the job status in the Request Data section above.

Step 4: Download the data

See Step 4: Download the data in the Request Data section above.