Skip to content

List staff

GET
/api/v1/providers

The appointments engine's staff members. Engine-guarded, ordered by id: see GET /api/v1/services for why.

serviceIds lists the services each staff member performs, the fact a program needs before it can offer anyone a slot. It is filtered to the key's own organization like every other field.

Authorization

bearerApiKey providers:read
AuthorizationBearer <token>

Build with a test key (sk_test_...): it works only in your API sandbox and never emails or texts anyone. Scopes, errors and limits.

In: header

Scope: providers:read

Query Parameters

limit?integer

Clamped, never rejected: values below 1 or unparseable fall back to 50, values above 200 become 200. A ?limit=1e9 from a program is far more likely to be a client bug than an attack, and answering 200 rows beats answering an error it retries in a loop.

Range1 <= value <= 200
Default50
cursor?string

The nextCursor from the previous response, passed back unchanged. Omit it for the first page. Opaque: it is base64url of an internal position and the encoding is not part of the contract; treat it as a token, do not construct one. A cursor this API did not issue is a 400 invalid_cursor rather than a silently-ignored parameter, because silently restarting at page one is how a paging loop becomes an infinite one.

The scheme is keyset (seek) paging on (order column, id), not OFFSET. OFFSET is wrong under concurrent writes: a booking created between page 1 and page 2 shifts every later row back by one, and the caller silently never sees whichever row slid across the boundary. Filters and limit may change between pages; the cursor only says where you got to.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/providers"
{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "email": "user@example.com",      "bio": "string",      "title": "string",      "active": true,      "avatarUrl": "string",      "onlineBookable": true,      "serviceIds": [        "a486dd3f-c8ab-4226-b78c-e435f821cb91"      ]    }  ],  "nextCursor": "string"}

List servicesGET

The appointments engine's bookable services. Engine-guarded: a key from a table-reservations organization gets `403 wrong_vertical` even if it holds `services:read`; the boundary is about what the organization is, not what happens to be stored for it. **Ordered by `id`, which is stable but arbitrary.** A business sells tens of services, so the first page of 200 is the whole list in practice; sort them yourself if you want them alphabetical. `active: false` services ARE returned, so a program reconciling against its own copy sees a service that was switched off instead of having it silently disappear. The public booking endpoints are where inactive services are filtered out.

Change an appointmentPATCH

A new time (or, for a table, a new party size) goes through the same change function as the guest's own change on their manage link: the venue's allocator, layouts, locks, hours and every other booking, leaving this booking out of its own way, then the deposit for the new time and party size; the booking window binds a new time. A change never takes money: one that would owe a deposit or a card the booking does not hold (a new time's service-period deposit, or a bigger party crossing the venue's deposit or card rule) is a `409 payment_required`. A party size change on a booking that already holds a deposit or a card is refused outright, for the venue to settle. The guest is told about a new time with the venue's usual change notice. Only a `confirmed` or `pending` booking that has not started can change. Send only the fields you are changing. The service and team member stay as booked.