How pagination and search work
Lists in the Sally API are paged, and search has its own endpoint per resource. This page explains the page envelope, why search takes its parameters in the request body and how search terms are matched.
Quick navigation
1. Pagination
Paged list endpoints take ?page (starting at 1, default 1) and ?pageSize (default 25, maximum 100). The answer is an envelope:
{ "page": 1, "pageSize": 25, "total": 137, "hasMore": true, "items": [ … ] }
total counts every match across all pages, and hasMore tells you whether another page follows. A few small lists are not paged and return a plain JSON array. The reference shows which kind each endpoint returns.
2. Search endpoints
Every searchable resource has a POST …/search endpoint that takes its parameters in the request body. That is deliberate: a search term in a URL runs into encoding trouble with spaces, umlauts and percent signs, in the body it does not.
POST /v1.0/directories/{directoryId}/appointments/search
{ "search": "Q4 planning", "from": "2026-09-01T00:00:00Z" }
A search body always has exactly one free-text field called search, matched across all relevant text fields of that resource at once, plus the structural filters of the resource and page and pageSize. The response has the same envelope as the matching list endpoint. Searchable are appointments, summaries, tasks, folders and the users of a company account.
The plain GET list endpoints stay pure list endpoints. The search endpoint is an addition, not a replacement.
3. How matching works
- Case-insensitive substring: the term matches anywhere in the value, not only at the start.
- Literal:
%,_and*are ordinary characters, not wildcards. - Trimmed: leading and trailing spaces are removed, and an empty term means no filter.
- Some endpoints require a minimum length, which the reference names on the endpoint.