How to Access Sandbox Data

The sandbox environment (sandbox.ab2d.cms.gov) is available to anyone who wants to try the API. You will need a bearer token to access the sandbox and authorize use of the AB2D endpoints.

What’s the difference between the sandbox and production environments?

API endpoints

AB2D endpoints are used to request sandbox data and API information. These endpoints are the same whether you’re in the sandbox or production environment.

Export

Create a job to request sandbox data. You should receive a response with the job ID (job_uuid).

GET /api/v2/fhir/Patient/$export

If it takes more than 30 hours to retrieve and download the data, the request will time out and fail. Try using parameters when running a job to filter the claims data returned and reduce file size.

Status

Once a job has been created, get a status update using the job ID from the first step. If the job is complete, the request will return a 200 response code. If it is in progress, it will return a 202 code.

GET /api/v2/fhir/Job/{job_uuid}/$status

Too many status requests can result in a “Retry-After” response in the header. Wait a short period of time before making any more requests.

Download

Once the job is complete, the response will return a list of file URLs. In each file URL, you can identify the job ID (job_uuid) and file name:

https://sandbox.ab2d.cms.gov/api/v2/fhir/Job/{job_uuid}/file/{file_name}

Download the file using the job ID and file name. Large files may take significantly longer to download. Files and job IDs expire and are removed after 72 hours.

GET /api/v2/fhir/Job/{job_uuid}/file/{file_name}

You can speed up download times by requesting compressed files in gzip format with the optional Accept-Encoding: gzip header in your command. Afterward, decompress (unzip) the gzip files into NDJSON format.

Cancellation

You can cancel a job, but only if it hasn’t been completed.

DELETE /api/v2/fhir/Job/{job_uuid}/$status

Other

Retrieve the server’s FHIR CapabilityStatement resource (required by the standard).

GET /api/v2/fhir/metadata

curl instructions

You can copy and paste curl commands into your terminal. In Confluence, use the code block macro. Learn how to install curl and jq.

HTTP responses are saved into shell variables named RESP<n>. Most steps also define shell variables used later in the process. For educational purposes it can be useful to examine variable values by entering echo ${variable}.

I. Start a job

Start an export job of FHIR ExplanationOfBenefit (EOB) resources using the following command:

RESP2=$(curl -i "https://sandbox.ab2d.cms.gov/api/v2/fhir/Patient/\$export?_type=ExplanationOfBenefit" \
  -H "Accept: application/fhir+json" \
  -H "Authorization: Bearer ${bearer_token}")

RESP2 is set to the headers of the HTTP response (by using the -i option of curl).

You’ll receive a response header with a content-location URL. This URL contains the job ID (e.g., 2356b9af-9257-41f4-9d82-4e27542ff1be):

HTTP/2 202
date: Thu, 09 Nov 2023 15:52:51 GMT
content-length: 0
content-location: https://sandbox.ab2d.cms.gov/api/v2/fhir/Job/2356b9af-9257-41f4-9d82-4e27542ff1be/$status

x-content-type-options: nosniff
x-xss-protection: 1; mode=block
cache-control: no-cache, no-store, max-age=0, must-revalidate
pragma: no-cache
expires: 0
strict-transport-security: max-age=31536000 ; includeSubDomains
x-frame-options: DENY

Use the job ID from the content-location URL to set the JOB_ID variable with the following command:

JOB_ID=$(echo $RESP2 | grep content-location | sed 's%^.*Job/\([^/]*\).*$%\1%')

II. Check the job status

Request the job status and save the HTTP response code into STATUS. If you receive a 200 response code, the job is complete. If you receive a 202 code, the job is in progress. In this case, continue checking the status until the job is complete.

curl -sw '%{http_code}' -o status.json "https://sandbox.ab2d.cms.gov/api/v2/fhir/Job/${job_id}/\$status"  \
  -H "Accept: application/fhir+json" \
  -H "Authorization: Bearer ${bearer_token}" | {
       read STATUS
       echo "Status: " $STATUS
  }

When the job is complete, the response will contain URLs for the export files to be downloaded. This is an example response returned after executing cat status.json | jq:

FILE=$(cat status.json | jq -r ".output[0].url" | sed 's%^.*file/\(.*$\)%\1%')

Extract the file name from RESP3 into the FILE variable with the following command:

FILE=$(cat status.json | jq -r ".output[0].url" | sed 's%^.*file/\(.*$\)%\1%')

III. Download your files

Download the data using the job ID and file name. This command downloads the data into the RESP4 variable. After retrieving sandbox data, follow the remaining steps in production access.

RESP4=$(curl "https://sandbox.ab2d.cms.gov/api/v2/fhir/Job/${job_uuid}/file/${file_name}" \
  -H "Accept: application/fhir+ndjson" \
  -H "Accept-Encoding: gzip" \
  -H "Authorization: Bearer ${bearer_token}")

You can speed up download times by requesting compressed files in gzip format with the optional Accept-Encoding: gzip header in your command. Afterward, decompress (unzip) the gzip files into NDJSON format.

Managing file size

The data for 100 enrollees is over 25MB. You can enter echo ${#RESP4} to check how many bytes a file is. This is too big for most text editors. Since the data is in NDJSON format, it consists of JSON objects separated by newlines.

The command echo $RESP | sed 1q | jq will extract the first JSON object and pretty print it using jq. The result is small enough to copy and paste into most editors. For exploring the data, it’s handy to use an editor that supports folding of JSON text, like the Intellij or VSCode.

Swagger instructions

These instructions walk you through how to authorize your bearer token, request sandbox data, and download your files using the AB2D Swagger UI.

I. Authorize your bearer token

1. Open the Select a definition dropdown menu in the top right corner.
2. Select V2 - FHIR R4. While you can use V1, we recommend using V2 for access to the _until parameter.
3. Select the Authorize button above the commands.
4. Enter your bearer token. It should be formatted as “Bearer {XXX}” where {XXX} is the value of your token. Each bearer token expires after 1 hour, so you will need a new token every time it expires.
5. Select Authorize.
6. If your bearer token is valid, you’ll be notified of your authorization. Select Close on this window.

II. Start a job

1. On the Swagger UI page, select the Export command /api/v2/fhir/Patient/$export
2. With the Export section expanded, select Try it out.
   • Keep the default values and add dates in ISO datetime format (yyyy-mm-dd’T’hh:mm:ss[+/-]hh:mm) for the parameter values. The _since and _until parameters filter for claims last updated since and until a specified date.
3. Select Execute. If the job was created successfully, you’ll receive a 202 HTTP response code under Server response.
4. Copy the job ID from the Response header. The job ID is located in the content-location URL (http://sandbox.ab2d.cms.gov/api/v2/fhir/Job/{job_uuid}/$status).

III. Check the job status

1. Select the Status command /api/v2/fhir/Job/{job_uuid}/$status
2. With the Status section expanded, select Try it out.
3. Paste the job ID (job_uuid) from step II.
4. Select Execute.
   • If the job is in progress, you’ll receive a 202 response code with a progress percentage by x-progress. Re-click Execute periodically until completion.
   • If the job is complete, you’ll receive a 200 code. The Response body will return a list of file URLs (https://sandbox.ab2d.cms.gov/api/v2/fhir/Job/{job_uuid}/file/{file_name}).

IV. Download your files

1. Select the Download command /api/v2/fhir/Job/{job_uuid}/file/{file_name}
2. With the Download section expanded, select Try it out.
3. Enter the job ID (job_uuid) and file name from step III.
   • You can speed up download times by requesting compressed files in gzip format with the optional Accept-Encoding: gzip header in your command. Afterward, decompress (unzip) the gzip files into NDJSON format.
4. Select Execute. If the download is successful, you’ll receive a 200 response code and a link to download the files.
5. Select Download file (under Response body). The file will be in NDJSON, where each line is a JSON object. You may need a text editor like JSON viewer to read the file.
6. If you are obtaining production access, send the AB2D team the job ID as instructed. Note that job IDs expire after 72 hours.

Troubleshooting

Visit our Troubleshooting Guide for guidance on HTTP response codes and common questions. If you need additional assistance, email the AB2D team at ab2d@cms.hhs.gov.

When contacting our team, please include the following information:

• Your operating system
• If applicable, your HTTP response code (e.g., 403, 400)
• A description of the issue including which stage of the process you’re on
• Any logs that may help us in resolving the issue