Filtering and pagination

This guide is for WX endpoints with a filter query parameter. It does not apply to Hire endpoints such as /api/v2/applicants; use the parameters on those endpoint pages instead.

Start with the endpoint's purpose and response schema. Add a filter only when you need fewer records, a smaller page or fewer response fields. Not every endpoint supports every option below.

Find matching records

Use filter[where] to describe the records you want. For example, a field equality condition uses this format:

filter[where][fieldName][eq]=value

Replace fieldName with a supported field. For example, this request finds the worker with the given UUID. --data-urlencode encodes the values for you and --get adds the parameters to the URL:

curl --get 'https://services.fountain.com/api/serviceworkforce/workers' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --data-urlencode 'filter[where][uuid][eq]=WORKER_UUID'

Replace ACCESS_TOKEN and WORKER_UUID with your values. Supported comparison operators include eq (equal), ne (not equal), gt/gte (greater than/at least), lt/lte (less than/at most), in and nin (in/not in a set), where the endpoint supports them. Use actual fields from the resource's schema, not its display title.

Combine conditions with and:

filter[where][and][0][fieldName1][eq]=value1&filter[where][and][1][fieldName2][eq]=value2

Read a page of results

filter[limit] controls the requested page size. filter[skip] skips records already read. For example:

curl --get 'https://services.fountain.com/api/serviceworkforce/workers' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --data-urlencode 'filter[limit]=25' \
  --data-urlencode 'filter[skip]=25'

This requests up to 25 workers after the first 25 matching records. Defaults and maximum page sizes vary by endpoint. Follow pagination through the complete result set when your integration needs every matching record.

When supported, use a stable sort such as filter[order][uuid]=asc for successive pages. Records can still change while you read them, so offset pagination is not a frozen snapshot.

Count matching records

Use /count when you need a number, not worker profiles:

curl --get 'https://services.fountain.com/api/serviceworkforce/workers/count' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --data-urlencode 'filter[where][uuid][eq]=WORKER_UUID'

This returns the number of matching records, not the records themselves. Omit limit and skip when you want a total rather than a window of results; use only the options exposed by that count endpoint.

Return only the fields you need

Endpoints supporting field selection use filter[fields]:

filter[fields][uuid]=true&filter[fields][firstName]=true

Request only fields supported by the endpoint. Field selection does not grant access to additional data.

Use bulk changes deliberately

Bulk update and delete endpoints can affect multiple records. Follow the endpoint's selection requirements and confirm the intended record IDs with a list request before submitting a bulk change.