Pagination, filtering, and sorting

Collection endpoints use the same query model. Each operation lists the exact public scalar fields available for filtering and sorting.

Pagination

Parameter	Default	Constraint
`page`	`1`	One-based integer
`pageSize`	`100`	Integer from `1` through `1000`

curl --get 'https://api.jobhandy.io/v1/employees' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'page=1' \
  --data-urlencode 'pageSize=250'

Reliable page traversal

Offset-style pagination is not a snapshot. Concurrent creates or updates can affect later pages. For repeatable incremental processing, use a stable business checkpoint and an explicit time window rather than assuming pages remain unchanged.

Page metadata and edge cases

Collection responses return page, pageSize, totalPages, totalElements, and items. The public contract does not separately define special behavior for an out-of-range page or the exact totalPages value when no records match. Use the values in the response rather than hard-coding an assumption.

Sorting

Use one endpoint-supported scalar field. Prefix it with - for descending order.

sort=createdAt
sort=-updatedAt

Multiple fields and whitespace are rejected. Null values sort first in ascending order and last in descending order.

A single sort field is not an idempotency or snapshot mechanism. Persist processed resource IDs or source checkpoints where duplicates would be harmful.

Created-at window

Where documented, createdAtFrom and createdAtTo are inclusive ISO-8601 UTC timestamps ending in Z.

createdAtFrom=2026-08-01T00:00:00.000Z
createdAtTo=2026-08-31T23:59:59.999Z

Filter operators

=  !=  >  >=  <  <=
IN (...)
CONTAINS
STARTS_WITH
ENDS_WITH
IS NULL
IS NOT NULL

AND binds before OR. Use parentheses when the intended grouping should be explicit.

blocked=false AND (countryCode="DE" OR countryCode="AT")

String values and quoting

String comparison is case-insensitive. These forms are supported:

lastName=Example
lastName="Example"
lastName='Example'

Values containing whitespace must be quoted:

lastName='van Example'
lastName="van Example"

Escape an apostrophe with a backslash:

lastName='O\'Example'
lastName="O\'Example"

The examples above show decoded filter expressions. URL-encode the complete query value. curl --data-urlencode is recommended.

curl --get 'https://api.jobhandy.io/v1/employees' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'filter=lastName="van Example"'

`IN`, null, and text operators

countryCode IN ("DE","AT","CH")
divisionId IS NULL
privateEmail IS NOT NULL
lastName STARTS_WITH "M"
additionalInfo CONTAINS "Building B"

Formal expression model

expression  = term, { "OR", term };
term        = factor, { "AND", factor };
factor      = comparison | "(", expression, ")";
comparison  = field, operator, value;

The endpoint controls which fields and operators are valid. A syntactically valid filter can still fail with UNSUPPORTED_FILTER_FIELD or UNSUPPORTED_FILTER_OPERATOR.

Query-size boundaries

The public contract does not state a separate maximum filter-expression length. Keep expressions bounded, prefer several targeted requests over one excessively complex expression, and handle normal request-validation or payload-limit responses.

Filter failures

Error code	Cause	Action
`INVALID_FILTER_SYNTAX`	Expression cannot be parsed	Check quoting, escaping, parentheses, and `IN` syntax
`UNSUPPORTED_FILTER_FIELD`	Field is not filterable on the endpoint	Use a field listed by the operation
`UNSUPPORTED_FILTER_OPERATOR`	Operator is not allowed for the field	Use a compatible operator
`UNSUPPORTED_SORT_FIELD`	Sort field is not allowed	Use one documented scalar field
`UNKNOWN_QUERY_PARAMETER`	Query name is not supported	Remove the unknown parameter

Get Started

Architecture & Concepts

Integration Guides

Operations

Pagination, filtering, and sorting

Reliable page traversal

Page metadata and edge cases

Sorting

Created-at window

Filter operators

String values and quoting

`IN`, null, and text operators

Formal expression model

Query-size boundaries

Filter failures

​Pagination

​Reliable page traversal

​Page metadata and edge cases

​Sorting

​Created-at window

​Filter operators

​String values and quoting

​IN, null, and text operators

​Formal expression model

​Query-size boundaries

​Filter failures

Pagination

Reliable page traversal

Page metadata and edge cases

Sorting

Created-at window

Filter operators

String values and quoting

`IN`, null, and text operators

Formal expression model

Query-size boundaries

Filter failures