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 offers 3 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
• _typeFilter: returns claims where the service-date matches the date range specified.

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
• ISO 8601 dates include colons (:) and for some time zones, plus signs (+). These characters must be percent-encoded in a URL. The percent-encoded example below also encodes the equal sign (=) and ampersand (&) in the query string.
  • Invalid example of an unencoded URL with both _since and _until parameters: https://sandbox.ab2d.cms.gov/api/v3/fhir/Patient/$export?_since=2023-06-15T00:00:00.000-05:00&_until=2024-06-15T00:00:00.000-05:00
  • Valid example of a percent-encoded URL with both _since and _until parameters: https://sandbox.ab2d.cms.gov/api/v3/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

AB2D v3 data became available in March 2026, therefore if you specify a date prior to March 26, 2026 (2026-03-26T00:00:00-05:00) with the _since parameter, your request will include a large amount of additional historical data for your enrollees that may cause your job to time out. The earliest possible date for the _since parameter is your organization’s attestation date.

If you need to load historical data, AB2D recommends using _typeFilter alone to query claims in biweekly or monthly increments by service date. If you have questions or need an alternative approach, contact the AB2D team at ab2d@cms.hhs.gov.

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

• ?_since%3D2026-04-10T03%3A00%3A00-04%3A00%26_until%3D2026-08-10T06%3A00%3A00-04%3A00

  The _until datetime is after the _since datetime. Both datetimes follow the ISO format and include time zones.

• ?_since%3D2026-04-10T16%3A00%3A00%2B00%3A00%26_until%3D3000-10-10T16%3A00%3A00%2B00%3A00

  The _until datetime is in the future. The job runs, and the value is replaced with the current date.

• ?_since%3D2026-04-10T00%3A00%3A00%26_until%3D2026-04-20T00%3A00%3A00

  The datetimes have no time zone.

• ?_since%3D2026-08-10T09%3A00%3A00-04%3A00%26_until%3D2026-04-10T07%3A00%3A00-04%3A00

  The _until datetime is before the _since datetime.

Example requests

Using the _since parameter only

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

curl -i "https://sandbox.ab2d.cms.gov/api/v3/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/v3/fhir/Patient/$export?_until=2026-09-01T00%3A00%3A00.000-04%3A00

curl -i "https://sandbox.ab2d.cms.gov/api/v3/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/v3/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/v3/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}"

The _typeFilter parameter

The _typeFilter parameter filters ExplanationOfBenefit resources by service date. The service date is the date care occurred within a billable period, stored in ExplanationOfBenefit.billablePeriod. The value of _typeFilter is a URL-encoded FHIR search query.

_since and _until filter by the lastUpdated timestamp. _typeFilter with service-date filters by the date that care took place. Use _since and _until to get claims that changed recently. Use _typeFilter to get claims for a specific period of care.

Examples of _typeFilter service date prefixes

To use _typeFilter to filter by service date, add a prefix directly before the date, with no space. Dates use the format YYYY-MM-DD.

Note: If a prefix isn’t added, it is assumed the service date is equal to the date specified.

Combining prefixes

To filter a date range, repeat service-date once for each prefix. A claim must match every filter to be returned.

Example request

The request below returns only ExplanationOfBenefit resources with a service date on or after January 1, 2025.

GET /api/v3/fhir/Patient/$export?_type=ExplanationOfBenefit&_typeFilter=ExplanationOfBenefit%3Fservice-date%3Dge2025-01-01

curl -i "https://sandbox.ab2d.cms.gov/api/v3/fhir/Patient/\$export?_type=ExplanationOfBenefit&_typeFilter=ExplanationOfBenefit%3Fservice-date%3Dge2025-01-01" \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async" \
    -H "Authorization: Bearer ${BEARER_TOKEN}"

The _outputFormat parameter

AB2D only returns claims data in Newline Delimited JSON (NDJSON) format by default, so the _outputFormat parameter is not required. If you include the _outputFormat parameter, use one of these values:

• application/fhir+ndjson
• application/ndjson
• ndjson

Any other value will return an error.

Running incremental exports

AB2D strongly recommends limiting each export to data updated since your last job. This is a best practice that keeps your data current and stops you from downloading the same claims repeatedly. It also helps you avoid requesting too much data at once, which can cause long job run times or even timeouts and failed jobs.

Add _since and _until parameters to every request you make to AB2D. Unlike prior versions of the API, AB2D v3 does not automatically set these parameters for you. As a result, a request with no parameters returns all your data, not just what’s new.

We recommend running jobs on a regular biweekly or monthly cadence. AB2D refreshes Parts A and B claims every Monday. Run your export after Monday’s refresh to get the most recent data.

You can use _typeFilter to filter claims by service date. If you need to load historical data, AB2D recommends using _typeFilter to query claims incrementally by service date.

How to run incremental exports

1. Record the _until value (or the completion datetime) of each export you download.
2. Use that value as _since on your next request.
3. Set _until explicitly so the window you requested is the window you receive.
4. Add _typeFilter when you only need certain claims. Each filtered request returns only what you specify, so track the date range you’ve covered for each filter.