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. A good value for this contract is
2021-01-01T00:00:00.000-05:00Enter this value 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