-
Notifications
You must be signed in to change notification settings - Fork 8
Making requests to AB2D v3
AB2D v3 documentation is subject to change during the Early Adopter Program.
Any issues or feedback on this documentation should be sent to AB2D@cms.hhs.gov.
AB2D v3 uses similar endpoints and workflows to AB2D v2. You can follow the same steps as you did in v2 to access v3 data, with the addition of the _typeFIlter parameter.
You’ll still need a bearer token to call the API. Use the production identity provider (idm.cms.gov), production URL (api.ab2d.cms.gov), and credentials issued by the AB2D team to access production data.
Create a job to request sandbox data. You should receive a response with the job ID (job_uuid).
GET /api/v3/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 “since” and “until” parameters when running a job to filter the claims data returned and reduce file size.
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/v3/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.
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/v3/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/v3/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.
You can cancel a job, but only if it hasn’t been completed.
DELETE /api/v3/fhir/Job/{job_uuid}/$status
v3 introduces the _typeFilter parameter for Bulk FHIR exports. AB2D v3 supports filtering ExplanationOfBenefit resources by service date using _typeFilter. A date range can be defined by providing less than lt and/or greater than gt values. This parameter can be included in a request one or more times.
service-date=gt2023-01-02&service-date=lt2023-05-01 - defines a range between January 2nd, 2023 and May 1st, 2023
service-date=gt2023-01-02 - defines a range between January 2nd, 2023 and today
service-date=lt2023-05-01 - defines a range from the earliest available records until May 1st, 2023
If the REST query would normally look like this: ExplanationOfBenefit?service-date=gt2022-01-01
The encoded parameter would look like this: ExplanationOfBenefit%3Fservice-date%3Dgt2022-01-01
The following is an example of entire sandbox endpoint with _typeFilter utilized for a three month service date range:
https://sandbox.ab2d.cms.gov/api/v2/fhir/Patient/$export?_typeFilter=ExplanationOfBenefit%3Fservice-date%3Dgt2022-01-01%26service-date%3Dlt2022-04-01