Filters

Filter, sort, and include related data in your API queries

List endpoints support filtering, sorting, and eager loading of related data to help you retrieve exactly the data you need.

Filtering

Use bracket-style query parameters to filter results by specific fields.

curl "https://wks-a1b2c3d4.provisionr.io/api/v1/directory/users?filter[state]=active&filter[name_search]=murphy" \
  -H "Authorization: Bearer prv-your-token"

Match Types

Filters support two match types depending on the field suffix.

Suffix	Match Type	Example	Description
filter[field]	Exact	filter[state]=active	Returns only exact matches
filter[field_search]	Partial	filter[name_search]=mur	Returns results containing the value

Date Range Filters

Use _before and _after suffixes to filter by date ranges.

# Users created in January 2026
curl "https://...?filter[created_after]=2026-01-01&filter[created_before]=2026-01-31" \
  -H "Authorization: Bearer prv-your-token"

Available date range filters vary by resource but commonly include:

Filter	Description
filter[created_before] / filter[created_after]	Filter by creation date
filter[updated_before] / filter[updated_after]	Filter by last update date
filter[expires_before] / filter[expires_after]	Filter by expiration date
filter[deleted_before] / filter[deleted_after]	Filter by deletion date

Soft Delete Visibility

Resources that support soft deletes can be filtered with the trashed parameter.

Value	Description
filter[trashed]=without	Exclude soft-deleted records (default)
filter[trashed]=with	Include soft-deleted records
filter[trashed]=only	Return only soft-deleted records

Sorting

Use the sort query parameter to order results. Prefix a field with - to sort in descending order.

# Sort by name ascending
curl "https://...?sort=name" \
  -H "Authorization: Bearer prv-your-token"

# Sort by created_at descending
curl "https://...?sort=-created_at" \
  -H "Authorization: Bearer prv-your-token"

Sort by multiple fields using a comma-separated list. Fields are applied in order of precedence.

# Sort by state ascending, then by name descending
curl "https://...?sort=state,-name" \
  -H "Authorization: Bearer prv-your-token"

Available sort fields vary by endpoint. Check the endpoint documentation for the list of supported sort options.

Includes

Use the include query parameter to eager load related data alongside the primary resource.

curl "https://...?include=attributes,attributes-count" \
  -H "Authorization: Bearer prv-your-token"

Include multiple relationships using a comma-separated list. Many resources support lightweight variants to check for the existence or count of related data without loading full records.

Suffix	Description
include=relation	Load the full related data
include=relation-count	Include a count of related records
include=relation-exists	Include a boolean indicating if related records exist

Available includes vary by endpoint. Check the endpoint documentation for the list of supported include options.

Combining Parameters

Filters, sorting, includes, and pagination can all be combined in a single request.

curl "https://wks-a1b2c3d4.provisionr.io/api/v1/directory/dimensions?filter[state]=active&filter[name_search]=dept&sort=-created_at&include=attributes-count&page=1" \
  -H "Authorization: Bearer prv-your-token"