List and search clients

Request

Searches the client base of the Location. Exact phone and email contact searches require clients:read_contact plus the subject contact permission; without that scope the API returns 403 missing_scope/permission_denied, not an empty result. Free-text query remains under clients:read. Contact fields use the redaction contract when contact access is absent. This endpoint is rate-limited.\n\nCursor-paginated list. Default ordering: id. Cursors use the cursor query parameter, expire after one hour, and are bound to the credential, tenant, list, and filters. Expired, malformed, foreign, or re-filtered cursors fail with 422 validation_failed using field codes expired_cursor, invalid_cursor, foreign_cursor, or filter_changed.

Security

OAuth2(Required scopes: clients:read) or ApiKey

Path

location_idintegerrequired

Identifier of the Location. Verified against the credential on every call — a Location the credential cannot access responds with 404.

Query

phonestring

Exact phone number to search for, in international format. Requires clients:read_contact; without it the response is 403, not an empty list.

emailstring, (email)

Exact email to search for. Requires clients:read_contact; without it the response is 403, not an empty list.

querystring

Free-text search across non-sensitive client display fields; contact-field exact search uses phone/email and requires clients:read_contact.

limitinteger, [ 1 .. 100 ]

Page size for cursor pagination. Default is 25; maximum is 100. Values outside 1..100 or non-integers fail with 422 validation_failed; the value is never clamped.

Default:25

cursorstring

Opaque cursor from next_cursor. An empty value is the same as omitting the parameter and returns the first page. Cursors expire one hour after the response that issued them (every page issues a fresh cursor) and are bound to credential, tenant, list, filters, and ordering; for OAuth the credential is the user's authorization, so a cursor survives a token refresh; a row whose ordering column changed between pages may be skipped or returned twice, and a row created while you page may be missing from this pass if it sorts before the current position (start a new pass to pick it up); expired, malformed, foreign, or re-filtered cursors fail with 422 validation_failed using field codes expired_cursor, invalid_cursor (also a cursor whose number of key values does not match the list's ordering), foreign_cursor (another credential or tenant), or filter_changed (another list, ordering, or filters).

curl -i -X GET \
  'https://developer.alteg.io/_mock/en/b2b-v3/openapi/locations/{location_id}/clients?phone=string&email=user%40example.com&query=string&limit=25&cursor=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

A page of clients matching the search.

Headers

RateLimit-Remaininginteger, (int32), >= 0

Requests left in the most constrained policy window that applies to this request.

RateLimit-Resetinteger, (int32), >= 0

On 429, seconds until the most constrained policy frees up; it equals Retry-After there. On a successful response it reports the length of that policy's window rather than the time left in the current one, so treat it as the window size, not as a countdown — the counter to pace against is RateLimit-Remaining.

RateLimit-Policystring

Most constrained policy applied to the request, as <limit>;w=<window in seconds>.

Example:"10;w=60"

X-Request-Idstring

Request identifier for support and log correlation.

Bodyapplication/json

dataArray of objects(Client)required

has_morebooleanrequired

Whether more items exist beyond this page.

next_cursorstring or nullrequired

Opaque cursor for the next page; null on the last page.

objectstringrequired

Value:"list"

Response

{
  "object": "list",
  "data": [
    { … }
  ],
  "has_more": false,
  "next_cursor": null
}