Postman Instructions

Sandbox and the Onboarding Process

After attesting and electing an AB2D Data Operations Specialist (ADOS), a PDP organization must demonstrate their ability to use the API to access Production by successfully retrieving synthetic claims data from the test (Sandbox) environment. In order to verify this requirement, PDP organizations must provide the AB2D team with the Job ID from a successful run in the test (Sandbox) environment.

AB2D Synthetic Data

AB2D provides four sample contracts that have been designed to provide synthetic data for testing purposes.

Simple Datasets- Two Contracts

This dataset provides contracts with a varying number of beneficiaries containing simple approximations of AB2D data. These contracts are ideal to test the stress of retrieving and downloading different sized data files. The data in these API payloads will not reflect the distribution of disease and demographic information you can expect from production data.

PDP Sponsor	Contract	Number of Benes
PDP-100	Z0000	100
PDP-10000	Z0010	10,000

Advanced Datasets- Two Contracts

This dataset provides contracts with sample data that is a more accurate representation of AB2D production data. They follow AB2D’s Bulk FHIR format and contain a more realistic distribution of disease and demographic information.

PDP Sponsor	Contract	Number of Benes
PDP-1001	Z1001	600-800
PDP-1002	Z1002	600-800

What does this instruction guide contain?

These instructions will guide you through the process of obtaining a JSON web token (JWT), also referred to as a bearer token, using Postman. Postman offers a Graphical User Interface (GUI) and provides an easy entrance point for users. Once complete, this token will be used to pull synthetic claims data by accessing test (Sandbox) API endpoints using another application called Swagger. The instructions below: Postman (Step 1) + Swagger (Step 2) are needed to access the Sandbox environment.

Step 1: Postman Instructions

The Postman directions below are broken up into the following sections:

• Downloading Postman
• Creating a new collection
• Saving a request
• Posting a request

Downloading Postman

Go to the Postman site here to download and install the app version of Postman. Because only the app version of Postman is allowed in Production, we promote the use of this version in Sandbox as well. The web version is available to you in Sandbox, but it will not be in Production. The directions below follow along with the app version of Postman.

You will then be directed to an account sign-in page. Note, you are able to directly access the app and skip sign-in by clicking the link at the bottom of the page as shown below.

Creating a new collection

Click on the orange + New button in the top left corner of the app.

Choose Create New to create a new Collection:

Configure as follows:
Name: ab2d
Choose: Create.

In the left hand panel, click on the three dot’s next the ab2d node you just created and choose Add Request:

Saving a request

Configure the “SAVE REQUEST” page as follows:

• Request name: retrieve-a-token
• Select: Save to ab2d at bottom right corner.

Posting a request

Click on GET, retrieve-a-token under the ab2d node and immediately, a new tab will appear to the right.

Alter the GET request to a POST request:

In the bar next to POST enter the following URL:
https://test.idp.idm.cms.gov/oauth2/aus2r7y3gdaFMKBol297/v1/token

Configure the Params tab as follows:

Key	Value
grant_type	client_credentials
scope	clientCreds

Configure the Headers tab as follows:
Choose one of the sample Base64-encoded credentials from a sample PDP Sponsor. This will be placed under the Value column by Authorization.

Simple Datasets
PDP Sponsor	Base64-encoded id: password
PDP-100	MG9hMnQwbHNyZFp3NXVXUngyOTc6SEhkdVdHNkxvZ0l2RElRdVdncDNabG85T1lNVmFsVHRINU9CY3VIdw==
PDP-10000	MG9hMnQwbG05cW9BdEpIcUMyOTc6eWJSNjBKbXRjcFJ0NlNBZUxtdmJxNmwtM1lEUkNaUC1XTjFBdDZ0Xw==

Advanced Datasets
PDP Sponsor	Base64-encoded id: password
PDP-1001	MG9hOWp5eDJ3OVowQW50TEUyOTc6aHNrYlB1LVlvV2ZHRFkxZ2NRcTM0QmZJRXlNVnVheXU4N3pXRGxpRw==
PDP-1002	MG9hOWp6MGUxZHlOZlJNbTYyOTc6c2huRzZOR2tIY3UyOXB0RHNLS1JXNnE1dUZKU1NwSXBkbF9LNWZWVw==

Key	Value
Content-Type	application/x-www-form-urlencoded
Accept	application/json
Authorization	Basic {Base64-encoded id:password}

Select Send.
In the body below you should see a token type, expires in statement, an access token, and scope statement as shown below:

You will use this bearer token, specified by the access_token value (in the next hour), to access Sandbox endpoints in Swagger, which we explain how to use below.

Step 2: Swagger Instructions

The Swagger directions below are broken into the following sections:

• Authorize your bearer token
• Export a Job ID
• Check the status of a job
• Download your Job ID

Authorize a bearer token

First - you must access the AB2D Swagger site by going here. Click “authorize” in the top right corner.

Use the bearer token (retrieved in the last 24 hours by you, and no other user) to authorize entry into the Sandbox endpoints. You will place this in the box under Value, adding the word Bearer before the token.

Be sure to leave a space between the word Bearer and the actual bearer token. Also remove any quotes from the token itself. Click Authorize.

You will see the following message:

Click Close to close the window.

Export a Job ID

AB2D supports both R4 and STU3 versions of the FHIR standard in both sandbox and production environments. FHIR R4 is available using v2 of AB2D while FHIR STU3 can be accessed via AB2D v1 which is typically indicated in an endpoint’s URL. Users are recommended to use AB2D v2 thus we will use that version in the examples/screenshots provided below. Users can select the AB2D API version they’d like to use in the Swagger interface by navigating to the dropdown menu in the right-hand corner of the page. Detailed descriptions of AB2D v1 (STU3) and AB2D v2 (R4) can be accessed in the AB2D Document Repository in Github.

Open the Export menu to view all possible endpoints:

Choose /api/v2/fhir/Patient/$export to initiate a Part A & B bulk claim export job. Then choose to Try it out in the right hand corner.

The default options are fine in this case with the exception of the _since date and _until date. A good value for the _since date for this contract is

2021-01-01T00:00:00.000-05:00

_until uses the same format as _since. A good value for the _until date is to use the current date and time, but you can enter any date as long as it is a date between _since and the current date and time.

Enter both of these values and click the big blue bar to Execute.

In the responses, look at the first code provided under Server response. Below that are all the other possible responses. The correct response should be a 202, which means Accepted. This means the job has been created.

From the information provided in the response, copy the Job ID from within the status request. Format:
content-location: http://sandbox.ab2d.cms.gov/api/v2/fhir/Job/{job id}/$status

Example:
content-location:
http://sandbox.ab2d.cms.gov/api/v2/fhir/Job/eeb77c0d-d9e2-4a7c-b6e6-c4ab8e0917ca/$status

Check the status of your job

While these are test jobs and most will run quickly, it is good practice to understand the steps associated with running a job, including checking its status.

Click on the Status menu to view the status endpoints:

Copy the Job ID from the Export step. Click on the GET /api/v2/fhir/{jobUuid}/$status endpoint, click Try it out and paste the Job ID into the box provided.

Click on the big blue bar labeled Execute.

In the responses, view the first value. This is the server response. There are two possible values, 202 or 200. If the response is 202, this means that the job is still in progress. It will give you an indication of the job progress from 1 to 100%.

An example of a partially finished job (36%) would be:

You will need to re-click on the Execute blue bar periodically until the status returns a 200. This means the job is done and the response will contain a list of files

These files can then be downloaded and contain the claim records for our sample job.

Download your Job Files

Click on the Download menu in swagger. Select the GET /api/v2/fhir/Job/{jobUuid}/file/{filename} endpoint to download a file. Click Try it out. Enter the Job ID of the job you created and the file name returned in the status, then press the Execute big blue bar.

It might take a while for the file to be downloaded depending on how big the job is. The Server response value should be a 200 and the Response body will contain a link to the claims data. To download the data into a file, click on the Download file link. This will be saved as an ndjson (new line delimited JSON, also known as JSON lines) file in your downloads. This data format will be identical to the production data. Only the Job ID from this file is needed - please send the Job ID to the AB2D team per the instructions emailed to your organizations assigned ADOS.

Questions?

Having issues or concerns - please get in touch.
ab2d@cms.hhs.gov - direct email
AB2D Google Group - join the conversation