Filter, Search & Sort

AgentSync APIs support filtering and sorting across collection endpoints, but the approach differs by API. ProducerSync API uses explicit query parameters. Contracting, Hierarchies, and Producer Profile APIs use a ?search= query language.

This page covers both approaches and explains how to apply them correctly.

Which API uses which approach?

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:

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

GET /v2/licenses?sort=state,asc

Multiple sort keys are supported:

GET /v2/licenses?sort=updatedAt,desc&sort=npn,asc

You can also sort by nested fields:

GET /v2/licenses?sort=licenseLoas.loaCode,desc

If no direction is specified, 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, Hierarchies & Producer Profile APIs — ?search= Query Language

These APIs use a structured ?search= parameter for flexible filtering. Rather than one parameter per field, you write filter expressions in a mini query language.

Overview

The search parameter accepts a comma-separated list of expressions:

?search=field1=value1,field2:value2

• Each expression is a filter condition
• Multiple expressions are combined using AND by default
• You can switch to OR logic using or=true

Basic Syntax

Each filter expression follows this format:

field operator value

Example:

GET /contracting/v1/customers/carriers?search=status=ACTIVE

Returns carriers where status = ACTIVE.

Combining Filters

AND logic (default):

GET /contracting/v1/customers/contractAssignments?search=status=ACTIVE,userDefined1=PRIORITY

Equivalent to: status = ACTIVE AND userDefined1 = PRIORITY

OR logic — include or=true:

GET /contracting/v1/customers/contractAssignments?search=status=ACTIVE,status=PENDING,or=true

Equivalent to: status = ACTIVE OR status = PENDING

⚠️ or=true applies to the entire query. Mixing AND and OR in a single request is not supported. Complex expressions like (A AND B) OR C are not possible.

Supported Operators

Operator Details

Equals (=)

Performs an exact match. Supported for strings, numbers, booleans, UUIDs, and dates (yyyy-MM-dd).

GET /contracting/v1/customers/carriers?search=status=ACTIVE
GET /contracting/v1/customers/contractAssignments?search=commissionLevelId=uuid-here

Null values:

GET /contracting/v1/customers/contractAssignments?search=writingNumber=null

Returns records where writingNumber is null.

Not Equals (!=)

Returns records where the value does not match.

GET /contracting/v1/customers/contractAssignments?search=status!=INACTIVE

⚠️ Behavior for != null may not work as a strict "is not null" filter. Test against your specific endpoint to confirm.

Contains / Like (:)

For string fields, performs a case-insensitive contains match:

GET /contracting/v1/customers/carriers?search=name:Acme

Matches: Acme Insurance, ACME Life, New Acme Holdings

For non-string fields, : behaves as an exact match.

⚠️ The behavior of : depends on field type — it is not always "contains."

Greater Than or Equal (>)

GET /contracting/v1/customers/contractAssignments?search=createdDate>2025-01-01

⚠️ For date fields, > is implemented as a bounded range:

createdDate BETWEEN 2025-01-01 AND today

It is not an unbounded "greater than" comparison.

Less Than or Equal (<)

GET /contracting/v1/customers/contractAssignments?search=createdDate<2025-12-31

Returns records on or before the given date.

In List (_in_)

Matches any value from a list. Wrap values in parentheses and separate with ;.

GET /contracting/v1/customers/contractAssignments?search=status_in_(ACTIVE;PENDING;APPROVED)

Equivalent to: status IN (ACTIVE, PENDING, APPROVED)

Numeric values:

GET /contracting/v1/customers/commissionLevels?search=level_in_(1;2;3)

Escaping Special Characters

If your value contains a reserved character, escape it with /.

Example — comma in value:

GET /contracting/v1/customers/carriers?search=name=Smith/, John

Matches the carrier named Smith, John.

Date Format

All dates must use yyyy-MM-dd:

GET /contracting/v1/customers/contractAssignments?search=createdDate=2025-03-01

Examples

Find active contract assignments:

GET /contracting/v1/customers/contractAssignments?search=status=ACTIVE

Find carriers whose name contains "Life":

GET /contracting/v1/customers/carriers?search=name:Life

Find contract assignments that are active AND have a writing number:

GET /contracting/v1/customers/contractAssignments?search=status=ACTIVE,writingNumber!=null

Find assignments in any of several statuses:

GET /contracting/v1/customers/contractAssignments?search=status_in_(ACTIVE;PENDING;APPROVED)

Find assignments created after a specific date:

GET /contracting/v1/customers/contractAssignments?search=createdDate>2025-01-01

Find assignments matching a custom field:

GET /contracting/v1/customers/contractAssignments?search=userDefined1=PRIORITY

Sorting

Contracting, Hierarchies, and Producer Profile APIs support ?sort=field,direction:

GET /contracting/v1/customers/contractAssignments?sort=createdDate,desc
GET /contracting/v1/organizations/ORG_ID/productHierarchies?sort=productName,asc

For multi-column sort, repeat the parameter:

GET /contracting/v1/customers/carriers?sort=name,asc&sort=createdDate,desc

If no direction is specified, default is ascending (asc). Default sort fields vary by endpoint — refer to the API Reference.

Common Pitfalls

• Date > is bounded to today — not an unbounded "greater than." Plan accordingly for open-ended queries.
• != null is unreliable — behavior varies; test against your endpoint.
• : is type-dependent — not always a contains match; behaves as exact match on non-string fields.
• Mixed AND/OR is unsupported — or=true applies to the whole expression; you can't group conditions.
• No nesting or grouping — all filters are flat; (A AND B) OR C is not expressible.

Operator Quick Reference