Skip to content
Recruso API

Responses and pagination

Conventions that hold across the API when a call succeeds. Failures have their own page — Errors — and endpoint-specific detail lives in the reference.

Pagination

Section titled “Pagination”

List endpoints come in two shapes, and the reference says which is which per operation.

Paged lists take pageNumber and pageSize query parameters:

GET /v1/clients?pageNumber=2&pageSize=10
  • pageNumber is 1-based and defaults to 1.
  • pageSize defaults to 25 and is capped at 100. Asking for more returns 100.

The response wraps the records in a paging envelope:

{
  "data": [ { "clientId": 101, "clientName": "Northgate Foods Ltd" } ],
  "pageNumber": 2,
  "pageSize": 10,
  "totalCount": 48,
  "pageCount": 5,
  "nextPage": "/clients?pageNumber=3&pageSize=10",
  "previousPage": "/clients?pageNumber=1&pageSize=10"
}

nextPage is null on the last page and previousPage is null on the first. pageCount is derived from totalCount and pageSize.

Unpaged lists return every accessible record in a named array, because the set is bounded by the agency’s own configuration. GET /v1/branches, for example, returns { "branches": [ … ] }. Do not send paging parameters to these; they are ignored.

Time zone

Section titled “Time zone”

Business data — bookings, plans, timesheets, payroll — is stored and returned in UK local time (GMT or BST), not UTC. During British Summer Time a value read as UTC is an hour out.

Authentication tokens are the exception: their lifetimes are UTC.

Week boundaries follow the agency’s configured work week rather than the calendar week; see Agencies.

Next

Section titled “Next”

Errors — the same conventions for the calls that fail.