Filter, Search & Sort
AgentSync APIs support filtering across collection endpoints, but the approach differs by API and version:
| API | Filtering Approach | Example |
|---|---|---|
| ProducerSync API | Explicit query parameters | ?states=MO,CA |
| Contracting API v2 / Hierarchies / Identity | Named snake_case query parameters | ?updated_since=2026-06-01T00:00:00Z |
ProducerSync API — Explicit Query Parameters
The ProducerSync API uses named query parameters for filtering. Each filterable field has its own parameter. To filter on multiple values for the same field, pass a comma-separated list.
Filtering
GET /v2/licenses?states=MO,CA
Returns licenses where the state is Missouri or California.
GET /v2/appointments?updatedSince=2025-01-01
Returns appointments updated on or after January 1, 2025.
Common ProducerSync filter parameters:
| Parameter | Description | Example |
|---|---|---|
npn | Filter to a specific NPN | ?npn=15645555 |
npns | Filter to multiple NPNs | ?npns=15645555,19855109 |
states | Filter to specific states | ?states=MO,CA,TX |
updatedSince | Return only records changed on or after a date (yyyy-MM-dd) | ?updatedSince=2025-06-01 |
includeDeleted | Include NIPR-deleted records (defaults to true) | ?includeDeleted=false |
Supported parameters vary by endpoint. Refer to the API Reference for the specific endpoint you are calling.
Sorting
Use ?sort=field,direction to order results:
GET /v2/licenses?sort=updatedAt,desc
Multiple sort keys are supported by repeating the parameter, and nested fields work with dot notation:
GET /v2/licenses?sort=updatedAt,desc&sort=npn,asc
GET /v2/licenses?sort=licenseLoas.loaCode,desc
If no direction is specified, the default is ascending (asc).
Field Selection
Use ?fields to request only specific fields, reducing payload size:
GET /v2/entities?fields=id,npn,firstName,lastName
Contracting v2, Hierarchies & Identity — Named Parameters
The v2 surfaces use explicit, self-documenting query parameters. Parameter names are lower_snake_case. There is no query-language filtering and no client-controlled sorting on v2 endpoints — list ordering is fixed by the server (stable across pagination runs).
updated_since — Incremental Sync
Available on the main list endpoints (/v2/producers, /v2/contracts, /v2/contract-assignments, /v2/contract-assignment-changes, /v2/assigned-* on Contracting; /v2/persons, /v2/bank-accounts on Identity):
GET /contracting/v2/contract-assignments?updated_since=2026-06-01T00:00:00Z
GET /identity/v2/persons?updated_since=2026-06-01T00:00:00Z
- RFC3339 UTC timestamp, inclusive — records modified at or after this instant.
- Modified time tracks any column change, so a returned record is not necessarily a business-meaningful change.
- Use it as a high-water mark: store when each sync run started and pass that on the next run. Overlap windows slightly — a pagination run is not a point-in-time snapshot.
Date-Scoped Views
| Parameter | Endpoints | Behavior |
|---|---|---|
as_of (yyyy-MM-dd) | GET /v2/organizations/{orgId}/hierarchies, GET /v2/organizations/{orgId}/responsible-upline-firms, available-uplines endpoints | Return the view as of a specific date (hierarchy snapshot; upline candidates whose commission-terms window covers the date) |
start_date / end_date (yyyy-MM-dd) | GET /v2/contract-assignments/{id}/available-uplines | Bound the prospective change's commission-terms window |
Resource Filters
| Parameter | Endpoint | Behavior |
|---|---|---|
firm_id (UUID) | GET /identity/v2/persons | Restrict results to persons associated with a firm. Returns 404 if the firm is not visible to you. |
Invalid parameter values return 400 with a message identifying the parameter — see API Status Codes.