{"openapi":"3.1.1","jsonSchemaDialect":"https://spec.openapis.org/oas/3.1/dialect/base","info":{"title":"pamprr Public API","summary":"The pamprr partner API: bookings, availability, clients, services, staff and locations for one business, by key.","version":"1.1.0","description":"The pamprr public API for partner integrations. Authenticate with a bearer API key minted in the operator's Settings, which carries an access setting (scopes); each operation names the one scope it requires. Every response carries X-Request-Id (quote it to support). Rate limited per key over a sliding sixty second window: the allowance in effect is authoritative in X-RateLimit-Limit on every authenticated response (100 today), every authenticated request counts, and a 429 carries Retry-After. Lists paginate by opaque cursor (nextCursor). Writes accept an Idempotency-Key so a retry replays the first outcome. Additive only: fields, headers, parameters, enum values and endpoints are added, never removed or renamed, without at least six months' notice, a period that is only ever extended, never shortened. Availability is computed live at the moment of the request from the same rules the business's own online booking calendar uses; it is advisory, and the create booking call is the truth. Every time is ISO 8601 UTC; every business runs on Europe/London today, and the business and location records name the zone, which is where a per business zone would appear. A key created with notifications on sends the customer the confirmation email and SMS on create and the app notification on cancel and reschedule, subject to the business's own notification settings and to the customer having an email, a phone or the pamprr app; a key with notifications off sends nothing."},"servers":[{"url":"https://pro.pamprr.me","description":"Production"}],"externalDocs":{"description":"The developer documentation","url":"https://pro.pamprr.me/developers"},"security":[{"bearerAuth":[]}],"tags":[{"name":"Business","description":"The record the key belongs to."},{"name":"Locations","description":"The business's branches."},{"name":"Staff","description":"The roster's partner projection."},{"name":"Services","description":"The menu, and who performs each service."},{"name":"Availability","description":"The bookable slots, computed live from the business's own calendar rules."},{"name":"Bookings","description":"The diary: list, create, read, cancel and reschedule."},{"name":"Clients","description":"The client book: list, create and read."}],"paths":{"/api/v1/business":{"get":{"tags":["Business"],"summary":"Get the calling key's business record","operationId":"getBusiness","x-pamprr-required-scope":"business:read","security":[{"bearerAuth":["business:read"]}],"description":"The business the key belongs to. Its names, slug and email, the time zone every time in this API is read against (Europe/London for every business today) and the currency every price is in (GBP, in pence).","responses":{"200":{"description":"Business record","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"business":{"$ref":"#/components/schemas/Business"}},"required":["business"]},"examples":{"business":{"summary":"The business the key belongs to","value":{"business":{"id":"00000000-0000-4000-8000-0000000b0001","name":"Example Studio Ltd","slug":"example-studio","displayName":"Example Studio","email":"hello@example.test","timezone":"Europe/London","currency":"GBP"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/bookings":{"get":{"tags":["Bookings"],"summary":"List bookings","operationId":"listBookings","x-pamprr-required-scope":"bookings:read","security":[{"bearerAuth":["bookings:read"]}],"description":"The bookings in a start time window, oldest first. With no status filter every status but cancelled is returned; ask for status=cancelled or status=all to see cancellations. To keep a copy in step, poll with updatedSince set to your last poll time, status=all and a wide window: every booking created, changed or cancelled since then comes back. Each row is the Booking projection; the operator's private notes are never included.","parameters":[{"name":"startDate","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Inclusive lower bound on start_time. Defaults to 30 days ago.","example":"2026-10-05"},{"name":"endDate","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Inclusive upper bound on start_time. Defaults to 90 days from now.","example":"2026-10-11"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","confirmed","in_progress","completed","cancelled","no_show","all"]},"description":"Only this status; all for every status. Absent: every status but cancelled. Any other word is refused with 400 VALIDATION_FAILED.","example":"all"},{"name":"updatedSince","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only bookings whose last change (updatedAt, else createdAt) is at or after this instant, inside the window. The order stays start time. A value that is not an ISO 8601 instant is refused with 400 VALIDATION_FAILED.","example":"2026-10-06T08:00:00Z"},{"name":"staffProfileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Only this staff member's bookings. A value that is not a UUID is refused with 400 VALIDATION_FAILED.","example":"00000000-0000-4000-8000-0000000000a1"},{"name":"locationId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Only this branch's bookings. A value that is not a UUID is refused with 400 VALIDATION_FAILED.","example":"00000000-0000-4000-8000-000000000c01"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Rows per page, 1 to 100 (a value above 100 is treated as 100).","example":50},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque keyset cursor from the previous page's nextCursor. Store and pass it back unchanged with the same filters; absent on the first page. A cursor never expires; one from another list, or from different filters, is refused with 400 INVALID_CURSOR.","example":"eyJ2IjoyLCJsIjoiYm9va2luZ3MiLCJrIjpbIjIwMjYtMTAtMDZUMDk6MTU6MDAuMDAwWiIsIjAwMDAwMDAwLTAwMDAtNDAwMC04MDAwLTAwMDAwMDAwMDBiMiJdLCJmIjoiNWQ0MTQwMmEifQ"}],"responses":{"200":{"description":"List of bookings scoped to the calling business","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"bookings":{"type":"array","items":{"$ref":"#/components/schemas/Booking"}},"nextCursor":{"type":["string","null"],"description":"Pass back as cursor to fetch the next page; null when this page was the last."}},"required":["bookings","nextCursor"]},"examples":{"window":{"summary":"Two bookings in the window, a second page to follow","value":{"bookings":[{"id":"00000000-0000-4000-8000-0000000000b1","customerName":"Alex Example","customerEmail":"alex@example.test","customerPhone":"+44 7700 900123","serviceName":"Signature Facial","serviceDuration":60,"staffName":"Maya Okafor","status":"confirmed","source":"online","paymentStatus":"deposit","startTime":"2026-10-06T09:15:00.000Z","endTime":"2026-10-06T10:15:00.000Z","priceInPence":6500,"notes":null,"createdAt":"2026-09-20T14:02:11.000Z","serviceId":"00000000-0000-4000-8000-0000000000e2","staffProfileId":"00000000-0000-4000-8000-0000000000a1","locationId":"00000000-0000-4000-8000-000000000c01","updatedAt":null,"cancelledAt":null},{"id":"00000000-0000-4000-8000-0000000000b2","customerName":"Sam Example","customerEmail":"sam@example.test","customerPhone":null,"serviceName":"Consultation","serviceDuration":30,"staffName":"Theo Brandt","status":"pending","source":"phone","paymentStatus":"unpaid","startTime":"2026-10-06T13:00:00.000Z","endTime":"2026-10-06T13:30:00.000Z","priceInPence":0,"notes":"First visit","createdAt":"2026-09-28T09:41:00.000Z","serviceId":"00000000-0000-4000-8000-0000000000e1","staffProfileId":"00000000-0000-4000-8000-0000000000a2","locationId":"00000000-0000-4000-8000-000000000c01","updatedAt":"2026-09-29T16:10:00.000Z","cancelledAt":null}],"nextCursor":"eyJ2IjoyLCJsIjoiYm9va2luZ3MiLCJrIjpbIjIwMjYtMTAtMDZUMDk6MTU6MDAuMDAwWiIsIjAwMDAwMDAwLTAwMDAtNDAwMC04MDAwLTAwMDAwMDAwMDBiMiJdLCJmIjoiNWQ0MTQwMmEifQ"}}}}}},"400":{"description":"The window or a filter is malformed: a date bound that does not parse (code INVALID_DATE_RANGE), a status outside the seven words, a non UUID id or an unparseable instant (code VALIDATION_FAILED), or a cursor that does not decode, names another list or was issued under other filters (code INVALID_CURSOR)","x-pamprr-variants":[{"$ref":"#/components/responses/BadRequest"},{"$ref":"#/components/responses/InvalidCursor"}],"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["Bookings"],"summary":"Create a booking","operationId":"createBooking","x-pamprr-required-scope":"bookings:write","security":[{"bearerAuth":["bookings:write"]}],"description":"Creates a booking on behalf of the calling business, confirmed and unpaid, recorded with the source api (the dashboard shows it as Partner). When the service's effective booking protection includes a deposit (deposit-only or both) and the business has Stripe live, the request is refused with 402 DEPOSIT_REQUIRED; when it is card capture, with 402 CARD_CAPTURE_REQUIRED; those bookings must be made through the consumer booking flow, which takes the deposit or the card. The slot must be free for the staff member: 409 BOOKING_OVERLAP when another booking has it, 409 SLOT_HELD while a customer is mid checkout for it (the hold frees itself within ten minutes if they abandon checkout). When the API key notifies customers, the customer receives the confirmation email with a calendar attachment if the booking carries an email, and the confirmation SMS if it carries a phone, subject to the business's own SMS settings. Send an Idempotency-Key so a retried request replays the first outcome instead of creating a second booking.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Optional but recommended: any string of 1 to 255 printable ASCII characters, a UUID v4 by preference, unique per request. For 24 hours the same key with the same request replays the first response (2xx, 4xx or 5xx alike) with Idempotent-Replayed: true; the same key with a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first request is still running is refused with 409 IDEMPOTENCY_REQUEST_IN_PROGRESS; a malformed key is refused with 400 IDEMPOTENCY_KEY_INVALID. Keys are scoped to your business, so a rotated API key still replays. Requests are processed once, with one qualification: a retry more than sixty seconds after a request that never completed may execute afresh, so in the rare event of a timeout retry with the same key promptly.","example":"0b3f6c2e-8f0a-4d5b-9c1e-7a2b3c4d5e6f"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBookingRequest"},"examples":{"concierge":{"summary":"A concierge books a facial with a named therapist at the Islington branch","value":{"customerName":"Alex Example","customerEmail":"alex@example.test","customerPhone":"+44 7700 900123","serviceId":"00000000-0000-4000-8000-0000000000e2","staffProfileId":"00000000-0000-4000-8000-0000000000a1","startTime":"2026-10-06T13:30:00.000Z","locationId":"00000000-0000-4000-8000-000000000c02","notes":"Booked by the hotel concierge"}}}}}},"responses":{"201":{"description":"Booking created (or, with Idempotent-Replayed: true, the stored outcome of the first request that carried this Idempotency-Key)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"},"X-Original-Request-Id":{"$ref":"#/components/headers/X-Original-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"booking":{"$ref":"#/components/schemas/Booking"}},"required":["booking"]},"examples":{"created":{"summary":"The booking as created: confirmed, unpaid, source api","value":{"booking":{"id":"00000000-0000-4000-8000-0000000000b3","customerName":"Alex Example","customerEmail":"alex@example.test","customerPhone":"+44 7700 900123","serviceName":"Signature Facial","serviceDuration":60,"staffName":"Maya Okafor","status":"confirmed","source":"api","paymentStatus":"unpaid","startTime":"2026-10-06T13:30:00.000Z","endTime":"2026-10-06T14:30:00.000Z","priceInPence":6500,"notes":"Booked by the hotel concierge","createdAt":"2026-10-06T08:31:12.000Z","serviceId":"00000000-0000-4000-8000-0000000000e2","staffProfileId":"00000000-0000-4000-8000-0000000000a1","locationId":"00000000-0000-4000-8000-000000000c02","updatedAt":null,"cancelledAt":null}}},"replayed":{"summary":"The same body on a retry with the same Idempotency-Key; the response carries Idempotent-Replayed: true and X-Original-Request-Id req_9a8b7c6d5e4f3a2b1c0d9e8f","value":{"booking":{"id":"00000000-0000-4000-8000-0000000000b3","customerName":"Alex Example","customerEmail":"alex@example.test","customerPhone":"+44 7700 900123","serviceName":"Signature Facial","serviceDuration":60,"staffName":"Maya Okafor","status":"confirmed","source":"api","paymentStatus":"unpaid","startTime":"2026-10-06T13:30:00.000Z","endTime":"2026-10-06T14:30:00.000Z","priceInPence":6500,"notes":"Booked by the hotel concierge","createdAt":"2026-10-06T08:31:12.000Z","serviceId":"00000000-0000-4000-8000-0000000000e2","staffProfileId":"00000000-0000-4000-8000-0000000000a1","locationId":"00000000-0000-4000-8000-000000000c02","updatedAt":null,"cancelledAt":null}}}}}}},"400":{"description":"The request is malformed: the body is not JSON (code INVALID_JSON), a required field is missing (code VALIDATION_FAILED), startTime does not parse (code INVALID_START_TIME) or is in the past (code PAST_START_TIME), the branch named is not usable or the staff member does not work there (code INVALID_LOCATION), or the Idempotency-Key is malformed (code IDEMPOTENCY_KEY_INVALID)","x-pamprr-variants":[{"$ref":"#/components/responses/BadRequest"},{"$ref":"#/components/responses/InvalidLocation"}],"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The booking must be made through the consumer booking flow: the service's effective booking protection includes a deposit and Stripe is live (code DEPOSIT_REQUIRED), or it is card capture and Stripe is live (code CARD_CAPTURE_REQUIRED)","x-pamprr-variants":[{"$ref":"#/components/responses/DepositRequired"},{"$ref":"#/components/responses/CardCaptureRequired"}],"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The slot is not free for the staff member: another booking has it (code BOOKING_OVERLAP) or a customer mid checkout holds it (code SLOT_HELD); or a retry while the first request carrying this Idempotency-Key is still being processed (code IDEMPOTENCY_REQUEST_IN_PROGRESS)","x-pamprr-variants":[{"$ref":"#/components/responses/Conflict"},{"$ref":"#/components/responses/SlotHeld"}],"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/bookings/{id}":{"get":{"tags":["Bookings"],"summary":"Get a booking","operationId":"getBooking","x-pamprr-required-scope":"bookings:read","security":[{"bearerAuth":["bookings:read"]}],"description":"One booking by id, the Booking projection: the same fields as a list row. A cancelled booking is returned (you asked for it by id). A booking that is not yours, or an id that is not a UUID, is 404 NOT_FOUND.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The booking id.","example":"00000000-0000-4000-8000-0000000000b3"}],"responses":{"200":{"description":"The booking","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"booking":{"$ref":"#/components/schemas/Booking"}},"required":["booking"]},"examples":{"booking":{"summary":"One booking by id, the same projection as a list row","value":{"booking":{"id":"00000000-0000-4000-8000-0000000000b3","customerName":"Alex Example","customerEmail":"alex@example.test","customerPhone":"+44 7700 900123","serviceName":"Signature Facial","serviceDuration":60,"staffName":"Maya Okafor","status":"confirmed","source":"api","paymentStatus":"unpaid","startTime":"2026-10-06T13:30:00.000Z","endTime":"2026-10-06T14:30:00.000Z","priceInPence":6500,"notes":"Booked by the hotel concierge","createdAt":"2026-10-06T08:31:12.000Z","serviceId":"00000000-0000-4000-8000-0000000000e2","staffProfileId":"00000000-0000-4000-8000-0000000000a1","locationId":"00000000-0000-4000-8000-000000000c02","updatedAt":null,"cancelledAt":null}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/bookings/{id}/cancel":{"post":{"tags":["Bookings"],"summary":"Cancel a booking","operationId":"cancelBooking","x-pamprr-required-scope":"bookings:write","security":[{"bearerAuth":["bookings:write"]}],"description":"Cancels a booking the way the business cancels one in its dashboard. The booking is marked cancelled with an optional reason, any unpaid checkout link for it is closed, anyone on the waiting list for the slot is notified, and the customer is told through the pamprr app if they booked with it and the API key notifies customers. Cancelling through the API does not refund a deposit or charge a late cancellation fee; refunds are made by the business in its dashboard. A booking that is already cancelled is returned as it stands with alreadyCancelled set, and nothing fires again. Send an Idempotency-Key so a retried request replays the first outcome.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The booking id.","example":"00000000-0000-4000-8000-0000000000b3"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Optional but recommended: the same rules as on create booking. For 24 hours the same key with the same request replays the first response; the same key against another booking is refused with 422 IDEMPOTENCY_KEY_REUSED.","example":"4e7d1c2b-8a9f-4b3e-a1c5-6d7e8f9a0b1c"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelBookingRequest"},"examples":{"withReason":{"summary":"A cancellation with a reason; an empty body is also allowed","value":{"reason":"Guest checked out early"}}}}}},"responses":{"200":{"description":"The booking as it now stands; alreadyCancelled is true when it was cancelled before this call and nothing fired","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"},"X-Original-Request-Id":{"$ref":"#/components/headers/X-Original-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"booking":{"$ref":"#/components/schemas/Booking"},"alreadyCancelled":{"type":"boolean","description":"True when the booking was cancelled before this call; the booking is returned as it stands and nothing fires again."}},"required":["booking","alreadyCancelled"]},"examples":{"cancelled":{"summary":"The booking cancelled by this call","value":{"booking":{"id":"00000000-0000-4000-8000-0000000000b3","customerName":"Alex Example","customerEmail":"alex@example.test","customerPhone":"+44 7700 900123","serviceName":"Signature Facial","serviceDuration":60,"staffName":"Maya Okafor","status":"cancelled","source":"api","paymentStatus":"unpaid","startTime":"2026-10-07T09:15:00.000Z","endTime":"2026-10-07T10:15:00.000Z","priceInPence":6500,"notes":"Booked by the hotel concierge","createdAt":"2026-10-06T08:31:12.000Z","serviceId":"00000000-0000-4000-8000-0000000000e2","staffProfileId":"00000000-0000-4000-8000-0000000000a1","locationId":"00000000-0000-4000-8000-000000000c02","updatedAt":"2026-10-06T08:45:30.000Z","cancelledAt":"2026-10-06T08:45:30.000Z"},"alreadyCancelled":false}},"alreadyCancelled":{"summary":"The booking was cancelled before this call; nothing fired","value":{"booking":{"id":"00000000-0000-4000-8000-0000000000b3","customerName":"Alex Example","customerEmail":"alex@example.test","customerPhone":"+44 7700 900123","serviceName":"Signature Facial","serviceDuration":60,"staffName":"Maya Okafor","status":"cancelled","source":"api","paymentStatus":"unpaid","startTime":"2026-10-07T09:15:00.000Z","endTime":"2026-10-07T10:15:00.000Z","priceInPence":6500,"notes":"Booked by the hotel concierge","createdAt":"2026-10-06T08:31:12.000Z","serviceId":"00000000-0000-4000-8000-0000000000e2","staffProfileId":"00000000-0000-4000-8000-0000000000a1","locationId":"00000000-0000-4000-8000-000000000c02","updatedAt":"2026-10-06T08:45:30.000Z","cancelledAt":"2026-10-06T08:45:30.000Z"},"alreadyCancelled":true}}}}}},"400":{"description":"The request is malformed: the body is not JSON (code INVALID_JSON), the reason is not a string of up to 500 characters (code VALIDATION_FAILED), or the Idempotency-Key is malformed (code IDEMPOTENCY_KEY_INVALID)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The booking cannot be cancelled: it is completed (code BOOKING_COMPLETED) or was marked as a no show (code BOOKING_NO_SHOW); or a retry while the first request carrying this Idempotency-Key is still being processed (code IDEMPOTENCY_REQUEST_IN_PROGRESS)","x-pamprr-variants":[{"$ref":"#/components/responses/BookingCompleted"},{"$ref":"#/components/responses/BookingNoShow"},{"$ref":"#/components/responses/Conflict"}],"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/bookings/{id}/reschedule":{"post":{"tags":["Bookings"],"summary":"Reschedule a booking","operationId":"rescheduleBooking","x-pamprr-required-scope":"bookings:write","security":[{"bearerAuth":["bookings:write"]}],"description":"Moves a booking to a new start time, and optionally to another staff member, the way the business does in its dashboard. The end time follows from the booking's own duration; the customer's reminders are reset for the new time; the customer is told through the pamprr app if they booked with it and the API key notifies customers. The new time must be free for the staff member: 409 BOOKING_OVERLAP when another booking has it, 409 SLOT_HELD while a customer is mid checkout for it. The API does not check the business's opening hours or the staff member's schedule for a reschedule, so check availability first. A new staff member must be one of your staff (404 otherwise) and must work at the booking's branch (400 INVALID_LOCATION otherwise). Send an Idempotency-Key so a retried request replays the first outcome.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The booking id.","example":"00000000-0000-4000-8000-0000000000b3"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Optional but recommended: the same rules as on create booking. For 24 hours the same key with the same request replays the first response; the same key against another booking or another time is refused with 422 IDEMPOTENCY_KEY_REUSED.","example":"9c2a5e71-4d0b-4f8e-9a6c-2b1d3e4f5a6b"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RescheduleBookingRequest"},"examples":{"nextMorning":{"summary":"Move the booking to the next morning, keeping the same therapist","value":{"startTime":"2026-10-07T09:15:00.000Z","staffProfileId":"00000000-0000-4000-8000-0000000000a1"}}}}}},"responses":{"200":{"description":"The booking at its new time","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"},"X-Original-Request-Id":{"$ref":"#/components/headers/X-Original-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"booking":{"$ref":"#/components/schemas/Booking"}},"required":["booking"]},"examples":{"moved":{"summary":"The booking at its new time; updatedAt set","value":{"booking":{"id":"00000000-0000-4000-8000-0000000000b3","customerName":"Alex Example","customerEmail":"alex@example.test","customerPhone":"+44 7700 900123","serviceName":"Signature Facial","serviceDuration":60,"staffName":"Maya Okafor","status":"confirmed","source":"api","paymentStatus":"unpaid","startTime":"2026-10-07T09:15:00.000Z","endTime":"2026-10-07T10:15:00.000Z","priceInPence":6500,"notes":"Booked by the hotel concierge","createdAt":"2026-10-06T08:31:12.000Z","serviceId":"00000000-0000-4000-8000-0000000000e2","staffProfileId":"00000000-0000-4000-8000-0000000000a1","locationId":"00000000-0000-4000-8000-000000000c02","updatedAt":"2026-10-06T08:40:02.000Z","cancelledAt":null}}}}}}},"400":{"description":"The request is malformed: the body is not JSON (code INVALID_JSON), startTime is missing or staffProfileId is not a UUID (code VALIDATION_FAILED), startTime does not parse (code INVALID_START_TIME) or is in the past (code PAST_START_TIME), the new staff member does not work at the booking's branch (code INVALID_LOCATION), or the Idempotency-Key is malformed (code IDEMPOTENCY_KEY_INVALID)","x-pamprr-variants":[{"$ref":"#/components/responses/BadRequest"},{"$ref":"#/components/responses/InvalidLocation"}],"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The booking cannot be moved: it is cancelled (code BOOKING_CANCELLED), completed (code BOOKING_COMPLETED) or was marked as a no show (code BOOKING_NO_SHOW); the new time is taken by another booking (code BOOKING_OVERLAP) or held by a customer mid checkout (code SLOT_HELD); or a retry while the first request carrying this Idempotency-Key is still being processed (code IDEMPOTENCY_REQUEST_IN_PROGRESS)","x-pamprr-variants":[{"$ref":"#/components/responses/BookingCancelled"},{"$ref":"#/components/responses/BookingCompleted"},{"$ref":"#/components/responses/BookingNoShow"},{"$ref":"#/components/responses/SlotHeld"},{"$ref":"#/components/responses/Conflict"}],"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/clients":{"get":{"tags":["Clients"],"summary":"List clients","operationId":"listClients","x-pamprr-required-scope":"clients:read","security":[{"bearerAuth":["clients:read"]}],"description":"The business's active clients by name. With search, only those whose name, email or phone contains the text (case insensitive, the text taken literally). Each row is the Client projection; the operator's private notes are never included.","parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":100},"description":"Only clients whose name, email or phone contains this text, case insensitive; the text is taken literally. Two to one hundred characters, otherwise 400 VALIDATION_FAILED.","example":"example"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Rows per page, 1 to 100 (a value above 100 is treated as 100).","example":50},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque keyset cursor from the previous page's nextCursor. Store and pass it back unchanged with the same filters; absent on the first page. A cursor never expires; one from another list, or from different filters, is refused with 400 INVALID_CURSOR.","example":"eyJ2IjoyLCJsIjoiY2xpZW50cyIsImsiOlsiU2FtIEV4YW1wbGUiLCIwMDAwMDAwMC0wMDAwLTQwMDAtODAwMC0wMDAwMDAwMDAwYzIiXSwiZiI6ImUzYjBjNDQyIn0"}],"responses":{"200":{"description":"List of clients scoped to the calling business","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"clients":{"type":"array","items":{"$ref":"#/components/schemas/Client"}},"nextCursor":{"type":["string","null"],"description":"Pass back as cursor to fetch the next page; null when this page was the last."}},"required":["clients","nextCursor"]},"examples":{"byName":{"summary":"The active clients matching the search, in name order","value":{"clients":[{"id":"00000000-0000-4000-8000-0000000000c1","name":"Alex Example","email":"alex@example.test","phone":"+44 7700 900123","createdAt":"2026-04-11T10:00:00.000Z","updatedAt":null},{"id":"00000000-0000-4000-8000-0000000000c2","name":"Sam Example","email":"sam@example.test","phone":null,"createdAt":"2026-09-28T09:40:00.000Z","updatedAt":"2026-09-29T16:10:00.000Z"}],"nextCursor":null}}}}}},"400":{"description":"The search text is under two or over one hundred characters (code VALIDATION_FAILED), or the cursor does not decode, names another list or was issued under other filters (code INVALID_CURSOR)","x-pamprr-variants":[{"$ref":"#/components/responses/BadRequest"},{"$ref":"#/components/responses/InvalidCursor"}],"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["Clients"],"summary":"Create a client","operationId":"createClient","x-pamprr-required-scope":"clients:write","security":[{"bearerAuth":["clients:write"]}],"description":"Creates a client record for the business, or returns the existing one. When an active client already has the given email (compared case insensitively) it is returned with existing set instead of a duplicate being created, and when only an archived client has it that record is restored and returned the same way, so the client id stays stable. The email is stored lower cased. Private notes cannot be set through the API. Send an Idempotency-Key so a retried request replays the first outcome.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Optional but recommended: the same rules as on create booking. For 24 hours the same key with the same request replays the first response (the 201 or the 200); the same key with a different request is refused with 422 IDEMPOTENCY_KEY_REUSED.","example":"7b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateClientRequest"},"examples":{"walkIn":{"summary":"A till adds a walk in; the email is stored lower cased","value":{"name":"Robin Example","email":"Robin@Example.test","phone":"+44 7700 900456"}}}}}},"responses":{"200":{"description":"A client with that email already exists (an archived one is restored); returned with existing set","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"},"X-Original-Request-Id":{"$ref":"#/components/headers/X-Original-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"client":{"$ref":"#/components/schemas/Client"},"existing":{"type":"boolean","enum":[true],"description":"Always true on this response: the client existed before this call."}},"required":["client","existing"]},"examples":{"existing":{"summary":"An active client already had that email (or an archived one was restored)","value":{"client":{"id":"00000000-0000-4000-8000-0000000000c1","name":"Alex Example","email":"alex@example.test","phone":"+44 7700 900123","createdAt":"2026-04-11T10:00:00.000Z","updatedAt":null},"existing":true}}}}}},"201":{"description":"Client created (or, with Idempotent-Replayed: true, the stored outcome of the first request that carried this Idempotency-Key)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"},"X-Original-Request-Id":{"$ref":"#/components/headers/X-Original-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"client":{"$ref":"#/components/schemas/Client"}},"required":["client"]},"examples":{"created":{"summary":"A new client record","value":{"client":{"id":"00000000-0000-4000-8000-0000000000c3","name":"Robin Example","email":"robin@example.test","phone":"+44 7700 900456","createdAt":"2026-10-06T08:50:00.000Z","updatedAt":null}}}}}}},"400":{"description":"The request is malformed: the body is not JSON (code INVALID_JSON), the name is missing or a field fails its rule (code VALIDATION_FAILED, with field naming it), or the Idempotency-Key is malformed (code IDEMPOTENCY_KEY_INVALID)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"A retry while the first request carrying this Idempotency-Key is still being processed (code IDEMPOTENCY_REQUEST_IN_PROGRESS; retry shortly)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/clients/{id}":{"get":{"tags":["Clients"],"summary":"Get a client","operationId":"getClient","x-pamprr-required-scope":"clients:read","security":[{"bearerAuth":["clients:read"]}],"description":"One client by id, the Client projection: the same fields as a list row. An archived client, a client that is not yours, or an id that is not a UUID is 404 NOT_FOUND.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The client id.","example":"00000000-0000-4000-8000-0000000000c1"}],"responses":{"200":{"description":"The client","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"client":{"$ref":"#/components/schemas/Client"}},"required":["client"]},"examples":{"client":{"summary":"One client by id","value":{"client":{"id":"00000000-0000-4000-8000-0000000000c1","name":"Alex Example","email":"alex@example.test","phone":"+44 7700 900123","createdAt":"2026-04-11T10:00:00.000Z","updatedAt":null}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/services":{"get":{"tags":["Services"],"summary":"List services","description":"The business's menu in its own order. Every service with its duration, price in pence, flags and the branches offering it; inactive services are returned with isActive false. Each row is the Service projection.","operationId":"listServices","x-pamprr-required-scope":"services:read","security":[{"bearerAuth":["services:read"]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Rows per page, 1 to 100 (a value above 100 is treated as 100).","example":50},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque keyset cursor from the previous page's nextCursor. Store and pass it back unchanged with the same filters; absent on the first page. A cursor never expires; one from another list, or from different filters, is refused with 400 INVALID_CURSOR.","example":"eyJ2IjoyLCJsIjoic2VydmljZXMiLCJrIjpbMiwiU2lnbmF0dXJlIEZhY2lhbCIsIjAwMDAwMDAwLTAwMDAtNDAwMC04MDAwLTAwMDAwMDAwMDBlMiJdLCJmIjoiZTNiMGM0NDIifQ"}],"responses":{"200":{"description":"List of services scoped to the calling business","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"services":{"type":"array","items":{"$ref":"#/components/schemas/Service"}},"nextCursor":{"type":["string","null"],"description":"Pass back as cursor to fetch the next page; null when this page was the last."}},"required":["services","nextCursor"]},"examples":{"menu":{"summary":"The first page of the menu, a second page to follow","value":{"services":[{"id":"00000000-0000-4000-8000-0000000000e1","name":"Consultation","description":"A thirty minute skin consultation.","durationMinutes":30,"priceInPence":0,"isActive":true,"isOnlineBookable":true,"isAddOn":false,"locationIds":["00000000-0000-4000-8000-000000000c01","00000000-0000-4000-8000-000000000c02"]},{"id":"00000000-0000-4000-8000-0000000000e2","name":"Signature Facial","description":null,"durationMinutes":60,"priceInPence":6500,"isActive":true,"isOnlineBookable":true,"isAddOn":false,"locationIds":["00000000-0000-4000-8000-000000000c01","00000000-0000-4000-8000-000000000c02"]}],"nextCursor":"eyJ2IjoyLCJsIjoic2VydmljZXMiLCJrIjpbMiwiU2lnbmF0dXJlIEZhY2lhbCIsIjAwMDAwMDAwLTAwMDAtNDAwMC04MDAwLTAwMDAwMDAwMDBlMiJdLCJmIjoiZTNiMGM0NDIifQ"}}}}}},"400":{"$ref":"#/components/responses/InvalidCursor"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/services/{id}/eligible-staff":{"get":{"tags":["Services"],"summary":"Eligible staff for a service","operationId":"listEligibleStaff","x-pamprr-required-scope":"services:read","security":[{"bearerAuth":["services:read"]}],"description":"Who can perform a service, and at which branches. The members assigned to the service who are bookable, each with locationIds narrowed to the visible branches where they can perform it (their branch memberships intersected with the branches offering the service), from the same rules the availability search applies. Every member listed can take a booking for this service at each listed branch, subject to hours and existing bookings; the availability search is the next call. A listed member need not have any free slot. The whole set, not paginated.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The service id from the services list. A service that is not yours, is deleted, is inactive or is offered at no branch customers can see is 404 NOT_FOUND.","example":"00000000-0000-4000-8000-0000000000e2"},{"name":"locationId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Only the members who can perform the service at this branch. A branch that is not one of your visible branches offering this service is refused with 400 INVALID_LOCATION; a value that is not a UUID with 400 VALIDATION_FAILED.","example":"00000000-0000-4000-8000-000000000c01"}],"responses":{"200":{"description":"The service, the branch asked for (or null) and the eligible members","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibleStaff"},"examples":{"eligible":{"summary":"Every bookable member assigned to the service, with the branches each can perform it at","value":{"serviceId":"00000000-0000-4000-8000-0000000000e2","serviceName":"Signature Facial","locationId":null,"staff":[{"id":"00000000-0000-4000-8000-0000000000a1","name":"Maya Okafor","initials":"MO","colour":"#6B8E4E","jobTitle":"Senior therapist","profileImageUrl":"https://example.test/images/maya.jpg","isBookable":true,"acceptsOnlineBookings":true,"deliveryMode":"both","locationIds":["00000000-0000-4000-8000-000000000c01","00000000-0000-4000-8000-000000000c02"]},{"id":"00000000-0000-4000-8000-0000000000a2","name":"Theo Brandt","initials":"TB","colour":"#C58B3F","jobTitle":"Facialist","profileImageUrl":null,"isBookable":true,"acceptsOnlineBookings":false,"deliveryMode":"fixed","locationIds":["00000000-0000-4000-8000-000000000c01"]}]}}}}}},"400":{"description":"locationId is not a UUID (code VALIDATION_FAILED), or names a branch that is not one of your visible branches offering this service (code INVALID_LOCATION)","x-pamprr-variants":[{"$ref":"#/components/responses/BadRequest"},{"$ref":"#/components/responses/InvalidLocation"}],"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/locations":{"get":{"tags":["Locations"],"summary":"List locations","operationId":"listLocations","x-pamprr-required-scope":"locations:read","security":[{"bearerAuth":["locations:read"]}],"description":"The business's branches, live ones only, the primary first. A branch the business has hidden from customers is listed with isVisible false: it cannot take a booking through the API or the online calendar, but the business still sees it. Every location carries timezone; every business runs on Europe/London today.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Rows per page, 1 to 100 (a value above 100 is treated as 100).","example":50},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque keyset cursor from the previous page's nextCursor. Store and pass it back unchanged with the same filters; absent on the first page. A cursor never expires; one from another list, or from different filters, is refused with 400 INVALID_CURSOR.","example":"eyJ2IjoyLCJsIjoibG9jYXRpb25zIiwiayI6WyIyMDI2LTAzLTAyVDA5OjAwOjAwLjAwMFoiLCIwMDAwMDAwMC0wMDAwLTQwMDAtODAwMC0wMDAwMDAwMDBjMDIiXSwiZiI6ImUzYjBjNDQyIn0"}],"responses":{"200":{"description":"List of locations scoped to the calling business","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"locations":{"type":"array","items":{"$ref":"#/components/schemas/Location"}},"nextCursor":{"type":["string","null"],"description":"Pass back as cursor to fetch the next page; null when this page was the last."}},"required":["locations","nextCursor"]},"examples":{"branches":{"summary":"Three branches, the primary first, one hidden from customers","value":{"locations":[{"id":"00000000-0000-4000-8000-000000000c01","name":"Example Studio, Soho","address":"12 Example Street","city":"London","postcode":"EX1 1EX","phone":"+44 20 7946 0100","email":"soho@example.test","website":"https://example.test","locationModel":"both","isPrimary":true,"isVisible":true,"timezone":"Europe/London","createdAt":"2026-03-02T09:00:00.000Z"},{"id":"00000000-0000-4000-8000-000000000c02","name":"Example Studio, Islington","address":"4 Sample Road","city":"London","postcode":"EX2 2EX","phone":"+44 20 7946 0101","email":null,"website":null,"locationModel":"fixed","isPrimary":false,"isVisible":true,"timezone":"Europe/London","createdAt":"2026-05-14T11:20:00.000Z"},{"id":"00000000-0000-4000-8000-000000000c03","name":"Example Studio, Pop up","address":null,"city":null,"postcode":null,"phone":null,"email":null,"website":null,"locationModel":null,"isPrimary":false,"isVisible":false,"timezone":"Europe/London","createdAt":"2026-08-01T08:00:00.000Z"}],"nextCursor":null}}}}}},"400":{"$ref":"#/components/responses/InvalidCursor"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/staff":{"get":{"tags":["Staff"],"summary":"List staff","operationId":"listStaff","x-pamprr-required-scope":"staff:read","security":[{"bearerAuth":["staff:read"]}],"description":"The roster's partner projection. The staff id a booking needs, the name, initials, colour, job title, photo, the bookable flags, the delivery mode, the home branch, the branches each member works at and the services each performs. Never contact or demographic fields. Filter by locationId for the members of one branch.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Rows per page, 1 to 100 (a value above 100 is treated as 100).","example":50},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque keyset cursor from the previous page's nextCursor. Store and pass it back unchanged with the same filters; absent on the first page. A cursor never expires; one from another list, or from different filters, is refused with 400 INVALID_CURSOR.","example":"eyJ2IjoyLCJsIjoic3RhZmYiLCJrIjpbIlRoZW8iLCJCcmFuZHQiLCIwMDAwMDAwMC0wMDAwLTQwMDAtODAwMC0wMDAwMDAwMDAwYTIiXSwiZiI6ImUzYjBjNDQyIn0"},{"name":"locationId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Only the members of this branch (a member works at every branch listed in locationIds). A branch that is not one of your business's live branches is refused with 400 INVALID_LOCATION; a value that is not a UUID with 400 VALIDATION_FAILED.","example":"00000000-0000-4000-8000-000000000c01"}],"responses":{"200":{"description":"List of staff scoped to the calling business","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"staff":{"type":"array","items":{"$ref":"#/components/schemas/Staff"}},"nextCursor":{"type":["string","null"],"description":"Pass back as cursor to fetch the next page; null when this page was the last."}},"required":["staff","nextCursor"]},"examples":{"roster":{"summary":"The members of one branch","value":{"staff":[{"id":"00000000-0000-4000-8000-0000000000a1","name":"Maya Okafor","initials":"MO","colour":"#6B8E4E","jobTitle":"Senior therapist","profileImageUrl":"https://example.test/images/maya.jpg","isBookable":true,"acceptsOnlineBookings":true,"deliveryMode":"both","homeLocationId":"00000000-0000-4000-8000-000000000c01","locationIds":["00000000-0000-4000-8000-000000000c01","00000000-0000-4000-8000-000000000c02"],"serviceIds":["00000000-0000-4000-8000-0000000000e1","00000000-0000-4000-8000-0000000000e2"],"createdAt":"2026-03-02T09:05:00.000Z"},{"id":"00000000-0000-4000-8000-0000000000a2","name":"Theo Brandt","initials":"TB","colour":"#C58B3F","jobTitle":"Facialist","profileImageUrl":null,"isBookable":true,"acceptsOnlineBookings":false,"deliveryMode":"fixed","homeLocationId":"00000000-0000-4000-8000-000000000c01","locationIds":["00000000-0000-4000-8000-000000000c01"],"serviceIds":["00000000-0000-4000-8000-0000000000e2"],"createdAt":"2026-06-10T10:00:00.000Z"}],"nextCursor":null}}}}}},"400":{"description":"locationId is not a UUID (code VALIDATION_FAILED), names a branch that is not one of your business's live branches (code INVALID_LOCATION), or the cursor does not decode, names another list or was issued under other filters (code INVALID_CURSOR)","x-pamprr-variants":[{"$ref":"#/components/responses/BadRequest"},{"$ref":"#/components/responses/InvalidLocation"},{"$ref":"#/components/responses/InvalidCursor"}],"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/availability":{"get":{"tags":["Availability"],"summary":"Availability search","operationId":"searchAvailability","x-pamprr-required-scope":"availability:read","security":[{"bearerAuth":["availability:read"]}],"description":"The bookable slots for a service, computed live from the same rules the business's own online booking calendar uses. Those rules, applied at the moment of the request: opening hours and closures, each staff member's schedule, existing bookings, customers mid checkout (their held slot reads as taken and frees itself within ten minutes if they abandon checkout), time blocks and travel time. Three modes: date for one day of slots; from with days (1 to 31) for a per day status; from with days (1 to 7) and detail=slots for the slots per day. Slots start on fifteen minute boundaries from the branch's opening time; today's slots start at least thirty minutes ahead. The answer is advisory: a booking or a checkout after it can take a slot, and the create booking call is the truth (409 BOOKING_OVERLAP when the slot is gone, 409 SLOT_HELD while a customer holds it). Every time is UTC; every business runs on Europe/London today and the response names the zone. Never cached.","parameters":[{"name":"serviceId","in":"query","required":true,"schema":{"type":"string","format":"uuid"},"description":"The service. Must be active and offered at a branch customers can see; otherwise 404 NOT_FOUND.","example":"00000000-0000-4000-8000-0000000000e2"},{"name":"date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"One day of slots (YYYY-MM-DD). Send date or from, never both.","example":"2026-10-06"},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"The first day of a window (YYYY-MM-DD).","example":"2026-10-05"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":31},"description":"With from: the window's length. 1 to 31 for the summary (default 14); 1 to 7 with detail=slots (default 7).","example":7},{"name":"detail","in":"query","required":false,"schema":{"type":"string","enum":["summary","slots"]},"description":"With from: summary (a status per day, the default) or slots (the slots per day, days capped at 7).","example":"slots"},{"name":"staffProfileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Only this staff member's slots. Must be one of your staff; otherwise 404 NOT_FOUND.","example":"00000000-0000-4000-8000-0000000000a2"},{"name":"locationId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Only this branch's slots. Must be a branch customers can see that offers the service; otherwise 400 INVALID_LOCATION.","example":"00000000-0000-4000-8000-000000000c01"},{"name":"deliveryMode","in":"query","required":false,"schema":{"type":"string","enum":["fixed","mobile"]},"description":"Restrict to staff who work at the branch (fixed) or travel to the customer (mobile); absent means either. Mobile applies the business's travel buffer between visits.","example":"fixed"}],"responses":{"200":{"description":"The slots for a day, the status per day, or the slots per day, by mode","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AvailabilityDay"},{"$ref":"#/components/schemas/AvailabilitySummary"},{"$ref":"#/components/schemas/AvailabilityWindow"}]},"examples":{"day":{"summary":"date: one day of slots","value":{"date":"2026-10-06","timezone":"Europe/London","serviceId":"00000000-0000-4000-8000-0000000000e2","slotMinutes":15,"durationMinutes":60,"slots":[{"startTime":"2026-10-06T09:15:00.000Z","endTime":"2026-10-06T10:15:00.000Z","localTime":"10:15","staff":[{"id":"00000000-0000-4000-8000-0000000000a1","name":"Maya Okafor","locationId":"00000000-0000-4000-8000-000000000c01"}]},{"startTime":"2026-10-06T13:30:00.000Z","endTime":"2026-10-06T14:30:00.000Z","localTime":"14:30","staff":[{"id":"00000000-0000-4000-8000-0000000000a1","name":"Maya Okafor","locationId":"00000000-0000-4000-8000-000000000c02"},{"id":"00000000-0000-4000-8000-0000000000a2","name":"Theo Brandt","locationId":"00000000-0000-4000-8000-000000000c01"}]}],"message":null}},"summary":{"summary":"from and days: a status per day","value":{"from":"2026-10-05","timezone":"Europe/London","serviceId":"00000000-0000-4000-8000-0000000000e2","days":[{"date":"2026-10-05","status":"fully_booked"},{"date":"2026-10-06","status":"available"},{"date":"2026-10-07","status":"available"},{"date":"2026-10-08","status":"available"},{"date":"2026-10-09","status":"available"},{"date":"2026-10-10","status":"available"},{"date":"2026-10-11","status":"closed"}],"message":null}},"window":{"summary":"from, days and detail=slots for one therapist: the slots per day","value":{"from":"2026-10-05","timezone":"Europe/London","serviceId":"00000000-0000-4000-8000-0000000000e2","slotMinutes":15,"durationMinutes":60,"days":[{"date":"2026-10-05","status":"fully_booked","slots":[]},{"date":"2026-10-06","status":"available","slots":[{"startTime":"2026-10-06T13:30:00.000Z","endTime":"2026-10-06T14:30:00.000Z","localTime":"14:30","staff":[{"id":"00000000-0000-4000-8000-0000000000a2","name":"Theo Brandt","locationId":"00000000-0000-4000-8000-000000000c01"}]}]},{"date":"2026-10-07","status":"available","slots":[{"startTime":"2026-10-07T09:00:00.000Z","endTime":"2026-10-07T10:00:00.000Z","localTime":"10:00","staff":[{"id":"00000000-0000-4000-8000-0000000000a2","name":"Theo Brandt","locationId":"00000000-0000-4000-8000-000000000c01"}]}]},{"date":"2026-10-08","status":"fully_booked","slots":[]},{"date":"2026-10-09","status":"available","slots":[{"startTime":"2026-10-09T10:15:00.000Z","endTime":"2026-10-09T11:15:00.000Z","localTime":"11:15","staff":[{"id":"00000000-0000-4000-8000-0000000000a2","name":"Theo Brandt","locationId":"00000000-0000-4000-8000-000000000c01"}]}]},{"date":"2026-10-10","status":"fully_booked","slots":[]},{"date":"2026-10-11","status":"closed","slots":[]}]}}}}}},"400":{"description":"A parameter fails its rule: serviceId missing, date and from together or neither, a malformed or impossible date, days out of range, detail=slots with days over 7, or a non UUID id (code VALIDATION_FAILED); or locationId names a branch that is not a visible branch offering the service (code INVALID_LOCATION)","x-pamprr-variants":[{"$ref":"#/components/responses/BadRequest"},{"$ref":"#/components/responses/InvalidLocation"}],"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Provide your pamprr_live_<secret> API key as Bearer <token>. Keys are minted in the operator Settings UI and revealed exactly once. Every key carries an access setting (a list of scopes such as bookings:read); each operation names the one scope it requires in x-pamprr-required-scope, and a key without it receives 403 FORBIDDEN. The security requirement on each operation names that scope as a role, the OpenAPI 3.1 form; x-pamprr-required-scope carries the same name for tools that ignore roles on http schemes."}},"headers":{"X-Request-Id":{"schema":{"type":"string","pattern":"^req_[0-9a-f]{24}$"},"description":"Server generated id for this request, present on every response. Quote it to support; it is meaningless otherwise."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"The allowance in effect for this key and endpoint, per sliding sixty second window (100 today). Authoritative: read it rather than hard coding the number. It may rise without notice and never falls without a deprecation notice. Present on every authenticated response; absent from a 429 raised by abuse protection rather than the allowance."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window after this one; 0 on a 429. Every authenticated request counts, errors and idempotent replays included."},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"ISO 8601 UTC timestamp by which the window will have fully cleared. An upper bound, not the exact moment one slot frees."},"Retry-After":{"schema":{"type":"integer"},"description":"Whole seconds to wait before retrying, rounded up. Present on every 429."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"RFC 6750 bearer challenge. On a 401: Bearer error=\"invalid_token\" when a credential was presented, or the bare challenge Bearer when none was. On a 403: Bearer error=\"insufficient_scope\", scope=\"<the required scope>\"."},"Idempotent-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present, with the value true, only when this response is the stored outcome of an earlier request that carried the same Idempotency-Key. The body is byte identical to the original."},"X-Original-Request-Id":{"schema":{"type":"string","pattern":"^req_[0-9a-f]{24}$"},"description":"On a replay: the id of the request that did the work. X-Request-Id names this request."}},"responses":{"BadRequest":{"description":"Malformed request (codes INVALID_JSON, VALIDATION_FAILED, INVALID_START_TIME, PAST_START_TIME, INVALID_LOCATION, INVALID_DATE_RANGE, on a list INVALID_CURSOR, on a write IDEMPOTENCY_KEY_INVALID)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INVALID_JSON":{"summary":"The body is not JSON","value":{"error":"Request body must be valid JSON.","code":"INVALID_JSON","requestId":"req_000000000000000000000001"}},"VALIDATION_FAILED":{"summary":"A value fails its rule; field names it where one is named","value":{"error":"locationId must be a UUID.","code":"VALIDATION_FAILED","field":"locationId","requestId":"req_000000000000000000000002"}},"INVALID_START_TIME":{"summary":"startTime does not parse","value":{"error":"Booking start time is not a valid ISO date.","code":"INVALID_START_TIME","requestId":"req_000000000000000000000003"}},"PAST_START_TIME":{"summary":"startTime is in the past","value":{"error":"Booking start time is in the past.","code":"PAST_START_TIME","requestId":"req_000000000000000000000004"}},"INVALID_LOCATION":{"summary":"The branch does not offer the service","value":{"error":"This service is not offered at the requested location.","code":"INVALID_LOCATION","requestId":"req_000000000000000000000005"}},"INVALID_DATE_RANGE":{"summary":"A date bound does not parse","value":{"error":"startDate and endDate must be valid ISO dates.","code":"INVALID_DATE_RANGE","requestId":"req_000000000000000000000006"}},"INVALID_CURSOR":{"summary":"The cursor does not decode or belongs to other filters","value":{"error":"The cursor is not valid for this list and these filters. Start again from the first page.","code":"INVALID_CURSOR","requestId":"req_000000000000000000000007"}},"IDEMPOTENCY_KEY_INVALID":{"summary":"The Idempotency-Key is malformed","value":{"error":"Idempotency-Key must be 1 to 255 printable ASCII characters; a UUID is recommended.","code":"IDEMPOTENCY_KEY_INVALID","requestId":"req_000000000000000000000008"}}}}}},"InvalidLocation":{"description":"The branch named is not one of your business's visible branches, does not offer the service, or the staff member does not work there (code INVALID_LOCATION)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INVALID_LOCATION":{"summary":"The staff member does not work at the branch","value":{"error":"This staff member is not available at the requested location.","code":"INVALID_LOCATION","requestId":"req_000000000000000000000009"}}}}}},"Unauthorized":{"description":"Missing or invalid API key (code UNAUTHORIZED). A key that verified but is revoked or expired says so in reason; anything that did not verify is the one collapsed refusal with no reason.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"WWW-Authenticate":{"$ref":"#/components/headers/WWW-Authenticate"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"reason":{"type":"string","enum":["revoked","expired"],"description":"Present only when the key verified: why it is refused."}}}]},"examples":{"invalid":{"summary":"No key, or a key that does not verify: the one collapsed refusal","value":{"error":"Invalid API key.","code":"UNAUTHORIZED","requestId":"req_00000000000000000000000a"}},"revoked":{"summary":"A verified key that was revoked","value":{"error":"This API key has been revoked.","code":"UNAUTHORIZED","reason":"revoked","requestId":"req_00000000000000000000000b"}},"expired":{"summary":"A verified key past its expiry","value":{"error":"This API key expired on 2026-12-01.","code":"UNAUTHORIZED","reason":"expired","requestId":"req_00000000000000000000000c"}}}}}},"Forbidden":{"description":"The key is valid but its access setting does not include the scope this endpoint requires (code FORBIDDEN; requiredScope names it). The request was authenticated and counted against the allowance.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"WWW-Authenticate":{"$ref":"#/components/headers/WWW-Authenticate"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"requiredScope":{"type":"string","description":"The scope the endpoint requires, e.g. bookings:write."}},"required":["requiredScope"]}]},"examples":{"FORBIDDEN":{"summary":"A read only key attempting a write","value":{"error":"This API key does not have the bookings:write scope.","code":"FORBIDDEN","requiredScope":"bookings:write","requestId":"req_00000000000000000000000d"}}}}}},"InvalidCursor":{"description":"The cursor does not decode, belongs to another list, was issued under different filters, or fails its type checks (code INVALID_CURSOR). Start again from the first page.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INVALID_CURSOR":{"summary":"Start again from the first page","value":{"error":"The cursor is not valid for this list and these filters. Start again from the first page.","code":"INVALID_CURSOR","requestId":"req_00000000000000000000000e"}}}}}},"IdempotencyKeyReused":{"description":"The Idempotency-Key was already used for a different request (a different method, path or body). Use a new key for a new request (code IDEMPOTENCY_KEY_REUSED).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"IDEMPOTENCY_KEY_REUSED":{"summary":"The same key with a different request","value":{"error":"This idempotency key was used for a different request. Use a new key for a new request.","code":"IDEMPOTENCY_KEY_REUSED","requestId":"req_00000000000000000000000f"}}}}}},"NotFound":{"description":"Resource not found (code NOT_FOUND)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"NOT_FOUND":{"summary":"Not yours, gone, archived, or not a UUID; the API never says which","value":{"error":"Booking not found.","code":"NOT_FOUND","requestId":"req_000000000000000000000010"}}}}}},"Conflict":{"description":"Resource conflict: an overlapping booking slot (code BOOKING_OVERLAP), or a retry while the first request carrying this Idempotency-Key is still being processed (code IDEMPOTENCY_REQUEST_IN_PROGRESS; retry shortly)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"BOOKING_OVERLAP":{"summary":"Another booking has the slot","value":{"error":"This time slot is already booked.","code":"BOOKING_OVERLAP","requestId":"req_000000000000000000000011"}},"IDEMPOTENCY_REQUEST_IN_PROGRESS":{"summary":"A retry while the first request is still running","value":{"error":"A request with this idempotency key is still being processed. Retry shortly.","code":"IDEMPOTENCY_REQUEST_IN_PROGRESS","requestId":"req_000000000000000000000012"}}}}}},"BookingCompleted":{"description":"The booking is completed; a completed booking cannot be cancelled or rescheduled through the API (code BOOKING_COMPLETED)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"BOOKING_COMPLETED":{"summary":"A completed booking cannot be cancelled or rescheduled through the API","value":{"error":"This booking is completed and cannot be cancelled through the API.","code":"BOOKING_COMPLETED","requestId":"req_000000000000000000000013"}}}}}},"BookingNoShow":{"description":"The booking was marked as a no show; it cannot be cancelled or rescheduled through the API (code BOOKING_NO_SHOW)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"BOOKING_NO_SHOW":{"summary":"A no show booking cannot be cancelled or rescheduled through the API","value":{"error":"This booking was marked as a no show and cannot be cancelled through the API.","code":"BOOKING_NO_SHOW","requestId":"req_000000000000000000000014"}}}}}},"BookingCancelled":{"description":"The booking is cancelled and cannot be rescheduled (code BOOKING_CANCELLED)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"BOOKING_CANCELLED":{"summary":"A cancelled booking cannot be rescheduled","value":{"error":"This booking is cancelled and cannot be rescheduled.","code":"BOOKING_CANCELLED","requestId":"req_000000000000000000000015"}}}}}},"SlotHeld":{"description":"A customer is mid checkout for this time with this staff member; the slot frees itself within ten minutes if they abandon checkout (code SLOT_HELD)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"SLOT_HELD":{"summary":"A customer is mid checkout for the slot","value":{"error":"Someone else is booking this time right now. It frees up in a few minutes if they do not complete their booking. Please choose another time or try again shortly.","code":"SLOT_HELD","requestId":"req_000000000000000000000016"}}}}}},"DepositRequired":{"description":"The service's effective booking protection includes a deposit and the business has Stripe live; the booking must be made through the consumer booking flow (code DEPOSIT_REQUIRED)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"DEPOSIT_REQUIRED":{"summary":"The service's effective booking protection includes a deposit and Stripe is live","value":{"error":"A deposit is required for this service. Bookings for this service must be made through the consumer booking flow.","code":"DEPOSIT_REQUIRED","requestId":"req_000000000000000000000017"}}}}}},"CardCaptureRequired":{"description":"The service's effective booking protection is card capture and the business has Stripe live; the booking needs a saved payment method and the customer's consent, which only the consumer booking flow can take (code CARD_CAPTURE_REQUIRED)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"CARD_CAPTURE_REQUIRED":{"summary":"The service's effective booking protection is card capture and Stripe is live","value":{"error":"This service requires a saved payment method and consent before booking. Bookings for this service must be made through the consumer booking flow.","code":"CARD_CAPTURE_REQUIRED","requestId":"req_000000000000000000000018"}}}}}},"RateLimited":{"description":"Rate limit exceeded (code RATE_LIMIT_EXCEEDED). Wait Retry-After seconds and retry. With X-RateLimit-Limit present the key's sliding sixty second allowance was exhausted; without it the refusal came from abuse protection and the same Retry-After rule applies.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"allowance":{"summary":"The key's sliding sixty second allowance is spent; X-RateLimit-Limit is present","value":{"error":"Rate limit exceeded.","code":"RATE_LIMIT_EXCEEDED","requestId":"req_000000000000000000000019"}},"abuseCeiling":{"summary":"Abuse protection refused before the key was checked; X-RateLimit-Limit is absent and the same Retry-After rule applies","value":{"error":"Rate limit exceeded.","code":"RATE_LIMIT_EXCEEDED","requestId":"req_00000000000000000000001a"}}}}}},"ServerError":{"description":"Unexpected server error (code INTERNAL_ERROR). The body carries no internal detail; quote the request id to support. The allowance headers are present when the request had authenticated and its allowance had been answered.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INTERNAL_ERROR":{"summary":"An unexpected failure; the body carries no internal detail","value":{"error":"Could not list bookings. Please try again.","code":"INTERNAL_ERROR","requestId":"req_00000000000000000000001b"}}}}}}},"schemas":{"Error":{"type":"object","description":"The one error envelope every 4xx and 5xx carries. Code specific fields may be added beside these.","properties":{"error":{"type":"string","description":"A sentence for a human."},"code":{"type":"string","description":"The machine readable code; branch on this, never on the message.","enum":["INVALID_JSON","VALIDATION_FAILED","INVALID_START_TIME","PAST_START_TIME","INVALID_LOCATION","INVALID_DATE_RANGE","INVALID_CURSOR","IDEMPOTENCY_KEY_INVALID","UNAUTHORIZED","DEPOSIT_REQUIRED","CARD_CAPTURE_REQUIRED","FORBIDDEN","NOT_FOUND","BOOKING_OVERLAP","BOOKING_COMPLETED","BOOKING_NO_SHOW","BOOKING_CANCELLED","SLOT_HELD","IDEMPOTENCY_REQUEST_IN_PROGRESS","IDEMPOTENCY_KEY_REUSED","RATE_LIMIT_EXCEEDED","INTERNAL_ERROR"]},"requestId":{"type":"string","pattern":"^req_[0-9a-f]{24}$","description":"The same id as the X-Request-Id header. Quote it to support."}},"required":["error","code","requestId"]},"Business":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"displayName":{"type":"string"},"email":{"type":["string","null"]},"timezone":{"type":"string","description":"The IANA zone the business runs on; Europe/London for every business today. Render local times with it; every time in this API is UTC."},"currency":{"type":"string","description":"The ISO 4217 code every price is in; GBP for every business today. Prices are in pence."}},"required":["id","name","slug","displayName","email","timezone","currency"]},"Client":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time","description":"When the client record last changed; null until it first changes after creation."}},"required":["id","name","email","phone","createdAt","updatedAt"]},"Service":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"durationMinutes":{"type":"integer"},"priceInPence":{"type":"integer"},"isActive":{"type":"boolean"},"isOnlineBookable":{"type":"boolean"},"isAddOn":{"type":"boolean"},"locationIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Branch ids the service is offered at, from the service_locations junction (Catalogue Stage 1). Always present; empty when the service has no offering rows."}},"required":["id","name","description","durationMinutes","priceInPence","isActive","isOnlineBookable","isAddOn","locationIds"]},"EligibleStaff":{"type":"object","description":"The members who can perform one service, and where.","properties":{"serviceId":{"type":"string","format":"uuid"},"serviceName":{"type":"string"},"locationId":{"type":["string","null"],"format":"uuid","description":"The branch asked for; null when the answer covers every offering branch."},"staff":{"type":"array","items":{"type":"object","description":"The Staff projection's presentation fields, with locationIds narrowed to the branches where this member can perform this service.","properties":{"id":{"type":"string","format":"uuid","description":"The staffProfileId a booking names."},"name":{"type":"string"},"initials":{"type":"string"},"colour":{"type":["string","null"]},"jobTitle":{"type":["string","null"]},"profileImageUrl":{"type":["string","null"]},"isBookable":{"type":"boolean"},"acceptsOnlineBookings":{"type":"boolean"},"deliveryMode":{"type":"string","enum":["fixed","mobile","both"]},"locationIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"The visible branches where this member can perform this service; the branch asked for alone when locationId was given."}},"required":["id","name","initials","isBookable","acceptsOnlineBookings","deliveryMode","locationIds"]}}},"required":["serviceId","serviceName","locationId","staff"]},"Location":{"type":"object","description":"A branch of the business. Never the whole row: no coordinates, catchment, travel or hours columns.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"address":{"type":["string","null"]},"city":{"type":["string","null"]},"postcode":{"type":["string","null"]},"phone":{"type":["string","null"],"description":"The branch's public contact, as shown to customers."},"email":{"type":["string","null"]},"website":{"type":["string","null"]},"locationModel":{"type":["string","null"],"enum":["fixed","mobile","both",null],"description":"Whether the branch takes customers at its address, travels to them, or both. Null on a legacy row."},"isPrimary":{"type":"boolean"},"isVisible":{"type":"boolean","description":"False when the business has hidden the branch from customers: it is live for the business but cannot take a booking through the API or the online calendar."},"timezone":{"type":"string","description":"The IANA zone the branch's hours and its bookings' local times are in. Europe/London for every business today; the field is where a per business zone would appear."},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","address","city","postcode","phone","email","website","locationModel","isPrimary","isVisible","timezone","createdAt"]},"Staff":{"type":"object","description":"A staff member's partner projection. Never email, phone, gender, pronouns, bio, specialisms, the not bookable reason or commission.","properties":{"id":{"type":"string","format":"uuid","description":"The staffProfileId a booking names."},"name":{"type":"string","description":"The display name, else the first and last names; the identity a booking's staffName snapshot carries."},"initials":{"type":"string"},"colour":{"type":["string","null"],"description":"The calendar colour."},"jobTitle":{"type":["string","null"]},"profileImageUrl":{"type":["string","null"]},"isBookable":{"type":"boolean"},"acceptsOnlineBookings":{"type":"boolean"},"deliveryMode":{"type":"string","enum":["fixed","mobile","both"]},"homeLocationId":{"type":["string","null"],"format":"uuid"},"locationIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Every branch the member works at, the home branch included."},"serviceIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"The services the member is assigned to perform."},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","initials","colour","jobTitle","profileImageUrl","isBookable","acceptsOnlineBookings","deliveryMode","homeLocationId","locationIds","serviceIds","createdAt"]},"AvailabilitySlot":{"type":"object","properties":{"startTime":{"type":"string","format":"date-time","description":"The slot's start, UTC."},"endTime":{"type":"string","format":"date-time","description":"The start plus the service's duration: the span a booking at this slot will occupy. Buffers between appointments are applied by the search and never appear here."},"localTime":{"type":"string","description":"The start as the business sees it, HH:MM in the response's timezone."},"staff":{"type":"array","description":"Who can take this slot, and the branch each would take it at.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"locationId":{"type":"string","format":"uuid"}},"required":["id","name","locationId"]}}},"required":["startTime","endTime","localTime","staff"]},"AvailabilityDay":{"type":"object","description":"The date mode: one day of slots.","properties":{"date":{"type":"string","format":"date"},"timezone":{"type":"string"},"serviceId":{"type":"string","format":"uuid"},"slotMinutes":{"type":"integer","description":"The step between candidate starts (15)."},"durationMinutes":{"type":"integer","description":"The service's duration."},"slots":{"type":"array","items":{"$ref":"#/components/schemas/AvailabilitySlot"}},"message":{"type":["string","null"],"description":"Why there are no slots when there are none: the business is closed that day, or no staff member can take the service in the requested mode."}},"required":["date","timezone","serviceId","slotMinutes","durationMinutes","slots","message"]},"AvailabilitySummary":{"type":"object","description":"The summary mode: a status per day over the window.","properties":{"from":{"type":"string","format":"date"},"timezone":{"type":"string"},"serviceId":{"type":"string","format":"uuid"},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"status":{"type":"string","enum":["available","fully_booked","closed"]}},"required":["date","status"]}},"message":{"type":["string","null"]}},"required":["from","timezone","serviceId","days","message"]},"AvailabilityWindow":{"type":"object","description":"The slot window mode (detail=slots): the slots per day over up to seven days.","properties":{"from":{"type":"string","format":"date"},"timezone":{"type":"string"},"serviceId":{"type":"string","format":"uuid"},"slotMinutes":{"type":"integer"},"durationMinutes":{"type":"integer"},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"status":{"type":"string","enum":["available","fully_booked","closed"]},"slots":{"type":"array","items":{"$ref":"#/components/schemas/AvailabilitySlot"}}},"required":["date","status","slots"]}}},"required":["from","timezone","serviceId","slotMinutes","durationMinutes","days"]},"Booking":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customerName":{"type":"string"},"customerEmail":{"type":["string","null"]},"customerPhone":{"type":["string","null"]},"serviceName":{"type":"string"},"serviceDuration":{"type":"integer"},"staffName":{"type":"string"},"status":{"type":"string","enum":["pending","confirmed","in_progress","completed","cancelled","no_show"]},"source":{"type":"string","enum":["online","assisted","walk_in","phone","api"],"description":"How the booking was made; api for a booking created through this API (the dashboard shows it as Partner)."},"paymentStatus":{"type":"string","enum":["unpaid","deposit","paid"]},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"priceInPence":{"type":["integer","null"]},"notes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"serviceId":{"type":["string","null"],"format":"uuid","description":"The service booked; null once that service is deleted (the serviceName snapshot remains)."},"staffProfileId":{"type":["string","null"],"format":"uuid","description":"The staff member; null once unassigned (the staffName snapshot remains)."},"locationId":{"type":["string","null"],"format":"uuid","description":"The branch; null on bookings made before branches were recorded."},"updatedAt":{"type":["string","null"],"format":"date-time","description":"When the booking last changed; null until it first changes after creation. The updatedSince filter reads this, else createdAt."},"cancelledAt":{"type":["string","null"],"format":"date-time","description":"When the booking was cancelled; null unless cancelled."}},"required":["id","customerName","customerEmail","customerPhone","serviceName","serviceDuration","staffName","status","source","paymentStatus","startTime","endTime","priceInPence","notes","createdAt","serviceId","staffProfileId","locationId","updatedAt","cancelledAt"]},"CreateBookingRequest":{"type":"object","properties":{"customerName":{"type":"string"},"customerEmail":{"type":["string","null"]},"customerPhone":{"type":["string","null"]},"serviceId":{"type":"string","format":"uuid"},"staffProfileId":{"type":"string","format":"uuid"},"startTime":{"type":"string","format":"date-time"},"notes":{"type":["string","null"]},"locationId":{"type":"string","format":"uuid","description":"Optional branch id. Validated when supplied (the branch must offer the service, be live and visible, and the staff member must belong to it; failures return 400 INVALID_LOCATION). When omitted the booking resolves to the single offering branch, else the staff member's home branch, else the primary location."}},"required":["customerName","serviceId","staffProfileId","startTime"]},"CancelBookingRequest":{"type":"object","description":"Optional; an empty body is allowed.","properties":{"reason":{"type":["string","null"],"maxLength":500,"description":"Free text recorded on the booking and its event, up to 500 characters."}}},"RescheduleBookingRequest":{"type":"object","properties":{"startTime":{"type":"string","format":"date-time","description":"The new start, in the future. The end follows from the booking's duration."},"staffProfileId":{"type":"string","format":"uuid","description":"Optional: move the booking to this staff member. One of your staff who works at the booking's branch; the staff name on the booking follows from the profile."}},"required":["startTime"]},"CreateClientRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"email":{"type":["string","null"],"maxLength":320,"description":"Stored lower cased; the duplicate check compares it case insensitively."},"phone":{"type":["string","null"],"maxLength":30}},"required":["name"]}}}}