Skip to content

Book an appointment

post/api/v1/appointments

Books an appointment for a client through the booking page's own writer: the time is re-checked against working hours, rotation, overrides, venue and special hours, blocks and the booking window, and the database refuses an overlap. The client gets the business's usual confirmation. The booking's source is api.

Idempotency-Key header required: a UUID you generate once per booking attempt and resend unchanged on every retry. The first answer is stored and every retry with the same key, from the same API key, with the same body gets that answer back, so a retried create never books twice. The same UUID with a different body, or from a different API key, is a 409. Stored answers include refusals: a 409 for a taken time replays as a 409, so a new attempt needs a new key. Answers are kept for at least a day.

A business that takes a deposit or a card is answered 402 payment_required with a link, never with an unpaid booking. The client's marketing consent is never set by this call.

Authorization

bearerApiKey appointments:write
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: appointments:write

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/appointments" \  -H "Content-Type: application/json" \  -d '{    "providerId": "4834bcdc-4a64-444d-966b-1a6fe381da24",    "startsAt": "string",    "customer": {      "name": "string",      "email": "user@example.com"    }  }'
{  "data": {}}