How to Filter Claims Data – V1
HTTP query parameters can help you efficiently maximize the value of the AB2D API. The default behavior of parameters supports the incremental export model and varies depending on your API version. You can use parameters while starting a job request in the sandbox or production environment.
Learn how to access sandbox data or production claims data.
AB2D recommends using V2 of the API
This documentation is for AB2D version 1, which implements the Bulk Data Access Implementation Guide V1.0.1. The _until parameter is only available with V2.
For organizations using V1, visit our V2 documentation to learn about parameters. Learn more about migrating from V1 to V2.
The _since parameter
The _since parameter allows users to filter claims data returned by date, which reduces duplication and speeds up job times. It follows the ISO datetime format (yyyy-mm-dd'T'hh:mm:ss[+|-]hh:mm). The time zone must be specified using + or - followed by hh:mm.
The _since parameter allows users to pull data that has been last updated since a specified date. The earliest possible date is January 1, 2020 (2020-01-01T00:00:00-05:00) or your organization’s attestation date, whichever is later. If no _since date is specified, it will default to your earliest possible date. It is highly recommended and considered best practice to use the _since parameter on V1 API calls.
The _until parameter filters for claims data last updated after a specified date. This parameter is only available with V2 (FHIR R4), the current and recommended version of the API.
Valid and invalid _since parameter values
| _since | Is it valid? | Why? |
|---|---|---|
| 2019-12-30T00:00:00.000+00:00 | No | The datetime is before January 1, 2020. The job will still run, but the value will be replaced with your earliest possible date. |
| 2020-10-10T00:00:00.000 | No | A timezone must be provided with the datetime. |
| 2020-10-10T16:00:00.000+10:00 | Yes | The datetime is after January 1, 2020 and follows the ISO format. |
| 2020-10-10T16:00:00.000-10:00 | Yes | The datetime is after January 1, 2020 and follows the ISO format. |
Why the _since parameter is important
In this scenario, your organization attests on March 1, 2020. Your organization runs its first job on November 1, 2020 and subsequently decides to pull data once a month. Your organization runs its second job on December 1, 2020.
Without the _since parameter
- The first job takes 4 hours to export all data available to you added between March 1, 2020 and November 1, 2020.
- The second job takes 4 and ½ hours to export all data available to you added between March 1, 2020 and December 1, 2020.
Without the _since parameter, the second job will pull all data from March 1st–December 1, 2020. Most of the data pulled is duplicate data. The only new data pulled is from the past month. Using the _since parameter can prevent this.
With the _since parameter
With the _since parameter manually set to November 1, 2020 on the second job:
- The first job takes 4 hours to export all data available to you between March 1, 2020 and November 1, 2020.
- The second job takes ½ hour to only export claims data available to you between November 1, 2020 and December 1, 2020.
With the _since parameter, the second job will only pull data from November 1–December 1. Only pulling data for the past month will be quicker and easier. Though a smaller number of claims may be pulled, a few may still be duplicates of already pulled claims.
Incremental export model overview
One recommended way to use AB2D is to periodically export any data that has been updated since your last job. We encourage bi-weekly exports to stay updated on new claims data. By using the _since parameter, you can filter for claims data last updated since your last job export. This way, you can run manual incremental exports.
Example scenario
- Start a job (JOB ID: ABC), successfully download the files, and save the datetime the job started. The datetime ABC starts will be the _since parameter value for your next job.
- Wait until the next bi-weekly update (the recommended frequency to run jobs).
- Start a job (JOB ID: DEF), manually entering the _since parameter with the datetime ABC started. The datetime DEF starts will be the _since parameter value for your next job.
- Repeat steps 2 and 3 indefinitely.
In this usage model, an organization only pulls the last 2 weeks of claims data delivered to the AB2D API. Please note there may be duplicates returned even when using the _since parameter. AB2D errs on the side of potentially providing a claim twice rather than potentially never providing a claim.
Example export workflow for parameters
The _since parameter can be used while starting an export job. Visit API Documentation to learn more about the expected workflow for the AB2D API. Review both unencoded and percent-encoded examples of the _since parameter. Note that ISO8601 dates include characters that can’t appear in URLs. Learn more about percent-encoding. Only the encoded versions will work, but the unencoded examples will show how the URL is formed before encoding.
Only _since parameter is specified
Unencoded
https://sandbox.ab2d.cms.gov/api/v2/fhir/Patient/$export?_since=2023-02-13T00:00:00.000-05:00
Percent-encoded
https://sandbox.ab2d.cms.gov/api/v2/fhir/Patient/$export?_since%3D2023-02-13T00%3A00%3A00.000-05%3A00
curl command
The _outputFormat parameter
The _outputFormat parameter allows you to request different formats for your data exports. The default and only format AB2D currently supports is application/fhir+NDJSON. The server must support Newline Delimited JSON (NDJSON), but may choose to support additional output formats. The server must also accept the full content type of application/fhir+NDJSON, as well as the abbreviated representations application/NDJSON and NDJSON.
