---
title: "Filter, Search & Sort"
description: "AgentSync APIs support filtering across collection endpoints, but the approach differs by API and version:"
url: "https://developer.agentsync.io/api-sorting-and-filtering"
image: "https://developer.agentsync.io/_og/d/c_Ocean.takumi,title_~RmlsdGVyLCBTZWFyY2ggJiBTb3J0,description_~QWdlbnRTeW5jIEFQSXMgc3VwcG9ydCBmaWx0ZXJpbmcgYWNyb3NzIGNvbGxlY3Rpb24gZW5kcG9pbnRzLCBidXQgdGhlIGFwcHJvYWNoIGRpZmZlcnMgYnkgQVBJIGFuZCB2ZXJzaW9uOg,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMxODdFRkYifX19,p_Ii9hcGktc29ydGluZy1hbmQtZmlsdGVyaW5nIg,s_URPWPGv5rim95Uqr.png"
---

# 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](#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](#filtering)

```http
GET /v2/licenses?states=MO,CA
```

Returns licenses where the state is Missouri **or** California.

```http
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](https://developer.agentsync.io/apis) for the specific endpoint you are calling.

### [Sorting](#sorting)

Use `?sort=field,direction` to order results:

```http
GET /v2/licenses?sort=updatedAt,desc
```

Multiple sort keys are supported by repeating the parameter, and nested fields work with dot notation:

```http
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](#field-selection)

Use `?fields` to request only specific fields, reducing payload size:

```http
GET /v2/entities?fields=id,npn,firstName,lastName
```

---

## [Contracting v2, Hierarchies & Identity — Named Parameters](#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](#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):

```http
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](#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](#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](https://developer.agentsync.io/api-status-codes).