HTTP Query Parameters - V2
HTTP query parameters filter or specify the claims data returned during requests. The AB2D API offers a variety of parameters, which can differ depending on what version you’re using. Once you have a good understanding of parameters you can use them to filter claims data.
AB2D recommends using V2 of the API
This documentation is for AB2D version 2, which implements the Bulk Data Access Implementation Guide V2.0.0. The _until parameter is only available with V2.
For organizations using V1, visit our V1 documentation to learn about parameters. Learn more about migrating from V1 to V2.
The _since and _until parameters
The _since and _until parameters let you filter claims data by date to reduce duplication and speed up job times. These parameters follow 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. These optional parameters can be used separately or together.
Separately, these parameters allow you to pull data that was last updated since or until a specified date. You can use the meta/lastUpdated property of each ExplanationOfBenefit (EOB) resource to see when each record was last updated. This will help you compare claims data when using the _since and _until parameters.
For _since
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 the datetime of your organization’s last successful export. If this is your first job, it will default to your earliest possible date.
For _until
The latest possible date is the current date. If no _until date is specified, it will default to the current date. You will receive an error if the _until date is in the future.
For _since and _until
Together, the _since and _until parameters allow you to pull data that was last updated within a certain date range. However, the _since parameter value must be an earlier date than the _until parameter value. In other words, the _since datetime must have occurred before the _until datetime.
Examples of default parameter behavior
| Parameters | Date range of export requests |
|---|---|
| _since = not set _until = not set |
From last successful and fully downloaded job date to current date |
| _since = 1/1/2023 _until = not set |
From 1/1/2023 to current date |
| _since = not set _until = 1/1/2024 |
From last successfully and fully downloaded job date to 1/1/2024 |
| _since = 1/1/2023 _until = 1/1/2024 |
From 1/1/2023 to 1/1/2024 |
Valid and invalid parameter values
| _since datetime | _until datetime | Is it valid? | Why? |
|---|---|---|---|
| 2020-10-10T00:00:00 | 2020-10-20T00:00:00 | No | A time zone must be provided with the datetime. |
| 2019-12-30T00:00:00+00:00 | 2020-01-14T00:00:00+00:00 | No | The _since datetime is before January 1, 2020. The job will still run, but the datetime will be replaced with the default. |
| 2020-10-10T16:00:00+00:00 | 3000-10-10T16:00:00+00:00 | No | The _until datetime is in the future. The job will still run, but the parameter value will be replaced with the current date. |
| 2020-10-10T09:00:00-08:00 | 2019-10-10T07:00:00-08:00 | No | The _until datetime is before the _since datetime. No data will be exported. |
| 2020-10-10T03:00:00-06:00 | 2021-10-10T06:00:00-06:00 | Yes | The _until datetime is after the _since datetime. The datetimes are valid and follow the ISO format with time zones. |
Parameter scenario for _since and _until
There may be use cases where a specific date range of claims data is required. For example:
- Your organization decides to incrementally export data and runs a job on December 1, 2023 for a month’s worth of data.
- The job takes 4 hours to export all the data updated between November 1, 2023 and December 1, 2023.
- Your organization realizes 1 week’s worth of data was corrupted in your database. Instead of rerunning the job, which would take 4 hours and result in duplicate data, you can use the _since and _until parameters to target the corrupted data.
- Your organization identifies the corrupted data as claims last updated between November 12, 2023 and November 18, 2023.
- Your organization runs a 2nd job with November 12, 2023 as the _since parameter value and November 18, 2023 as the _until parameter value.
- The job takes less than 1 hour to export the week’s worth of missing data from your database.
Review more example scenarios for the _since parameter.
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.
