How to Filter Claims Data

You can use HTTP query parameters to filter claims data returned during an API job request. To learn how to access data, see How to Access Sandbox Data and How to Access Production Claims Data.

AB2D v2 offers 2 query parameters to filter or specify the data returned:

• _since: returns claims last updated after a specified date
• _until: returns claims last updated before a specified date

AB2D also supports the _outputFormat parameter, which is covered at the end of this page.

Note: Use parameters when you start a job in the sandbox or production environment to speed up download times and reduce file size.

The _since and _until parameters

The _since and _until parameters filter claims data by the date it was last updated.

• You can use the parameters separately or together.
• Dates must use the ISO datetime format (yyyy-mm-dd’T’hh:mm:ss[+|-]hh:mm).
  • Sample date: July 1, 2026, 12:00 PM Eastern Daylight Time
  • Formatted sample: 2026-07-01T12:00:00.000-04:00
• Note the ISO8601 dates include characters that can’t appear in URLs.
  • Here is an example of invalid, unencoded URL utilizing both _since and _until parameters: https://sandbox.ab2d.cms.gov/api/v2/fhir/Patient/$export?_since=2023-06-15T00:00:00.000-05:00&_until=2024-06-15T00:00:00.000-05:00
  • Here is an example of valid, percent-encoded URL utilizing both _since and _until parameters: https://sandbox.ab2d.cms.gov/api/v2/fhir/Patient/$export?_since%3D2023-06-15T00%3A00%3A00.000-05%3A00%26_until%3D2024-06-15T00%3A00%3A00.000-05%3A00
  • Read more about percent-encoding here.

Date limitations for the _since parameter

The earliest possible date you can retrieve data for is either April 1, 2026 (2026-04-01T00:00:00-05:00) or your organization’s attestation date, whichever is later. If no _since date is specified, your export defaults to the datetime of your organization’s last successful export. If this is your first job, results will default to your earliest possible date.

Date limitations for the _until parameter

The latest possible date you can retrieve data for 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 you entered is in the future.

Date limitations when using the _since and _until parameters together

Use the _since and _until parameters together to specify a date range (i.e., to export data since [a date] until [a date]). If you accidentally enter a _since date that falls after the _until date the job will fail.

Default behaviors with the _since and _until parameters together

Examples of valid and invalid values

Valid values

• ?_since%3D2026-04-10T03%3A00%3A00-04%3A00%26_until%3D2026-08-10T06%3A00%3A00-04%3A00
  Why this works: The _until datetime is after the _since datetime. Both datetimes follow the ISO format and include time zones.

Invalid values, but the job still runs

• ?_since%3D2026-02-01T00%3A00%3A00-05%3A00%26_until%3D2026-08-01T00%3A00%3A00-04%3A00
  Why this works: The _since datetime is before the earliest possible date. The job runs, and the value is replaced with the default.

• ?_since%3D2026-04-10T16%3A00%3A00%2B00%3A00%26_until%3D3000-10-10T16%3A00%3A00%2B00%3A00
  Why this works: The _until datetime is in the future. The job runs, and the value is replaced with the current date.

Invalid values, the job fails or returns no data

• ?_since%3D2026-04-10T00%3A00%3A00%26_until%3D2026-04-20T00%3A00%3A00
  Why this doesn’t work: The datetimes have no time zone.

• ?_since%3D2026-08-10T09%3A00%3A00-04%3A00%26_until%3D2026-04-10T07%3A00%3A00-04%3A00
  Why this doesn’t work: The _until datetime is before the _since datetime.

Example requests

Using the _since parameter only

GET /api/v2/fhir/Patient/$export?_since=2026-07-01T00%3A00%3A00.000-04%3A00

curl -i "https://sandbox.ab2d.cms.gov/api/v2/fhir/Patient/\$export?_since=2026-07-01T00%3A00%3A00.000-04%3A00" \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async" \
    -H "Authorization: Bearer ${BEARER_TOKEN}"

Using the _until parameter only

GET /api/v2/fhir/Patient/$export?_until=2026-09-01T00%3A00%3A00.000-04%3A00

curl -i "https://sandbox.ab2d.cms.gov/api/v2/fhir/Patient/\$export?_until=2026-09-01T00%3A00%3A00.000-04%3A00" \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async" \
    -H "Authorization: Bearer ${BEARER_TOKEN}"

Using both the _since and _until parameters

GET /api/v2/fhir/Patient/$export?_since=2026-04-01T00%3A00%3A00.000-04%3A00&_until=2026-09-01T00%3A00%3A00.000-04%3A00

curl -i "https://sandbox.ab2d.cms.gov/api/v2/fhir/Patient/\$export?_since=2026-04-01T00%3A00%3A00.000-04%3A00&_until=2026-09-01T00%3A00%3A00.000-04%3A00" \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async" \
    -H "Authorization: Bearer ${BEARER_TOKEN}"

Incremental export model

One recommended way to use AB2D is to periodically export any data that has been updated since your last job. The AB2D team encourages bi-weekly exports to stay updated on new claims.

Incremental exports occur by default when you start a job, even without using parameters, so no further action is required. This is because _since defaults to the datetime of your last successful export, and _until defaults to the current datetime.

Example scenario

This is a scenario demonstrating how the default capability works for _since and _until:

1. You start your first job (JOB ID: ABC).
2. Once the job is complete, you download the files.
3. You wait until the next bi-weekly update (the recommended frequency to run jobs).
4. You start a new job (JOB ID: DEF).
5. You forget to download the files until after they’ve expired (72 hours).
6. You start another job (JOB ID: GHI). The _since value will default to when you started job ABC, not job DEF. This is because no files were downloaded with job DEF, so it wasn’t completed successfully.
7. Once the job is complete, download the files.
8. Repeat these steps.

In this usage model, AB2D automatically populates the _since value with the datetime of your last successfully completed export. For Job GHI, this is the date job ABC was created. Job DEF isn’t considered a successfully completed export since its files weren’t downloaded.