From a key to the first successful call in three steps.
Mint a key
In Settings, Operations, API keys, create a key with the Read only access setting, copy it from the one time reveal, and store it in your server's environment as PAMPRR_API_KEY.
Make the first call
Ask who the key belongs to. The answer is your business record: its id, names, slug, email, time zone and currency.
Then the diary
List services, staff and locations to learn the ids a booking needs, search availability for a free slot, and, with a key that carries bookings:write, create the booking.
Every call carries the key as a bearer token; the key is the business.
Send the key as Authorization: Bearer with every request. The API is server to server: keep the key in your backend's environment, never in a browser page or a mobile app.
A key is minted by an owner or admin in Settings, Operations, API keys, revealed once, and never stored in plain text by pamprr.
The first eight characters after the prefix are what the Settings list shows, so they are safe to quote; the rest is the secret.
A missing key, a malformed key and a key that does not verify all receive the same 401 with the code UNAUTHORIZED and no reason.
A key that verified but is revoked or expired receives the same code with a reason, because only the holder of the full secret can learn it.
Every 401 carries a WWW-Authenticate challenge.
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.
Header
What it says
WWW-Authenticate
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>".
Access and scopes
A key carries an access setting; each endpoint requires exactly one scope.
The Settings picker offers Read only (the default, every read scope), Full access (every scope) and Custom (read or write per resource).
Your business record is always readable.
A write scope stores its read scope beside it.
A call outside the key's access receives 403 FORBIDDEN with requiredScope naming the scope it lacks; the request was authenticated and counted against the allowance.
JSON. Send Content-Type: application/json on a write. Every response body is a JSON object.
Times
ISO 8601 in UTC with a Z suffix. Every business runs on Europe/London today; the business and location records name the zone, and availability answers carry a localTime beside each UTC start.
Money
Integers in pence. The business record names the currency; GBP for every business today.
Ids
UUIDs. A path id that is not a UUID, or that names another business's record, answers 404.
Names
camelCase fields. Absent values are null, never omitted.
Envelopes
A list answers { <resource>: [...], nextCursor }; a single record answers { business }, { booking } or { client }; a cancel adds alreadyCancelled and a client create may add existing; the availability search and the eligible staff answer their own object.
Host
One host, https://pro.pamprr.me, and one version prefix, /api/v1, carried by every path.
Errors
One envelope on every 4xx and 5xx; branch on the code, never on the sentence.
Every error body is { error, code, requestId }: a sentence for a human, the word your software branches on, and the id to quote to support. Some codes add a field beside those three, shown in the catalogue below.
Status
Meaning on this API
200
The call worked: a read, a change, or a client that already existed.
201
A booking or a client was created.
400
The request is malformed, a value is out of bounds, a cursor is bad, an idempotency key is malformed, or a branch is not usable.
401
No key, a key that does not verify, or a key that is revoked or expired.
402
The booking must be made through the consumer booking flow: a deposit or a saved card is required.
403
The key verified but lacks the scope the endpoint requires.
404
Not yours, gone, archived, or not a UUID; the API never says which.
409
The state refuses the change: a taken or held slot, a terminal booking, or a retry still in flight.
422
The idempotency key was already used for a different request.
429
Too many requests: the allowance, or abuse protection.
500
Something went wrong at pamprr; quote the request id.
Code
Status
When
Example body
INVALID_JSON
400
The body is not JSON
{"error":"Request body must be valid JSON.","code":"INVALID_JSON","requestId":"req_000000000000000000000001"}
VALIDATION_FAILED
400
A value fails its rule; field names it where one is named
{"error":"locationId must be a UUID.","code":"VALIDATION_FAILED","field":"locationId","requestId":"req_000000000000000000000002"}
INVALID_START_TIME
400
startTime does not parse
{"error":"Booking start time is not a valid ISO date.","code":"INVALID_START_TIME","requestId":"req_000000000000000000000003"}
PAST_START_TIME
400
startTime is in the past
{"error":"Booking start time is in the past.","code":"PAST_START_TIME","requestId":"req_000000000000000000000004"}
INVALID_LOCATION
400
The branch does not offer the service
{"error":"This service is not offered at the requested location.","code":"INVALID_LOCATION","requestId":"req_000000000000000000000005"}
INVALID_DATE_RANGE
400
A date bound does not parse
{"error":"startDate and endDate must be valid ISO dates.","code":"INVALID_DATE_RANGE","requestId":"req_000000000000000000000006"}
INVALID_CURSOR
400
The cursor does not decode or belongs to other filters
{"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
400
The Idempotency-Key is malformed
{"error":"Idempotency-Key must be 1 to 255 printable ASCII characters; a UUID is recommended.","code":"IDEMPOTENCY_KEY_INVALID","requestId":"req_000000000000000000000008"}
UNAUTHORIZED
401
No key, or a key that does not verify: the one collapsed refusal
{"error":"Invalid API key.","code":"UNAUTHORIZED","requestId":"req_00000000000000000000000a"}
DEPOSIT_REQUIRED
402
The service's effective booking protection includes a deposit and Stripe is live
{"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"}
CARD_CAPTURE_REQUIRED
402
The service's effective booking protection is card capture and Stripe is live
{"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"}
FORBIDDEN
403
A read only key attempting a write
{"error":"This API key does not have the bookings:write scope.","code":"FORBIDDEN","requiredScope":"bookings:write","requestId":"req_00000000000000000000000d"}
NOT_FOUND
404
Not yours, gone, archived, or not a UUID; the API never says which
{"error":"Booking not found.","code":"NOT_FOUND","requestId":"req_000000000000000000000010"}
BOOKING_OVERLAP
409
Another booking has the slot
{"error":"This time slot is already booked.","code":"BOOKING_OVERLAP","requestId":"req_000000000000000000000011"}
BOOKING_COMPLETED
409
A completed booking cannot be cancelled or rescheduled through the API
{"error":"This booking is completed and cannot be cancelled through the API.","code":"BOOKING_COMPLETED","requestId":"req_000000000000000000000013"}
BOOKING_NO_SHOW
409
A no show booking cannot be cancelled or rescheduled through the API
{"error":"This booking was marked as a no show and cannot be cancelled through the API.","code":"BOOKING_NO_SHOW","requestId":"req_000000000000000000000014"}
BOOKING_CANCELLED
409
A cancelled booking cannot be rescheduled
{"error":"This booking is cancelled and cannot be rescheduled.","code":"BOOKING_CANCELLED","requestId":"req_000000000000000000000015"}
SLOT_HELD
409
A customer is mid checkout for the slot
{"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"}
IDEMPOTENCY_REQUEST_IN_PROGRESS
409
A retry while the first request is still running
{"error":"A request with this idempotency key is still being processed. Retry shortly.","code":"IDEMPOTENCY_REQUEST_IN_PROGRESS","requestId":"req_000000000000000000000012"}
WEBHOOK_LIMIT_REACHED
409
Ten live endpoints already
{"error":"This business already has 10 webhook endpoints.","code":"WEBHOOK_LIMIT_REACHED","requestId":"req_00000000000000000000001c"}
WEBHOOK_ENDPOINT_DISABLED
409
A test on a disabled endpoint
{"error":"This endpoint is disabled (failing). Enable it before sending a test.","code":"WEBHOOK_ENDPOINT_DISABLED","requestId":"req_00000000000000000000001d"}
WEBHOOK_DELIVERY_PENDING
409
A replay of a delivery still on the ladder
{"error":"This delivery is still pending and will be attempted on schedule.","code":"WEBHOOK_DELIVERY_PENDING","requestId":"req_00000000000000000000001e"}
IDEMPOTENCY_KEY_REUSED
422
The same key with a different request
{"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"}
RATE_LIMIT_EXCEEDED
429
The key's sliding sixty second allowance is spent; X-RateLimit-Limit is present
An unexpected failure; the body carries no internal detail
{"error":"Could not list bookings. Please try again.","code":"INTERNAL_ERROR","requestId":"req_00000000000000000000001b"}
Rate limits
One allowance per key over a sliding sixty second window, stated on every authenticated response.
Header
What it says
X-RateLimit-Limit
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
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
ISO 8601 UTC timestamp by which the window will have fully cleared. An upper bound, not the exact moment one slot frees.
Retry-After
Whole seconds to wait before retrying, rounded up. Present on every 429.
Pagination
The lists page by an opaque cursor; the eligible staff answer is the whole set.
limit: Rows per page, 1 to 100 (a value above 100 is treated as 100).
cursor: 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.
nextCursor: Pass back as cursor to fetch the next page; null when this page was the last.
Idempotency
A write retried with the same key replays the first outcome.
Idempotency-Key: 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.
Header
What it says
Idempotent-Replayed
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
On a replay: the id of the request that did the work. X-Request-Id names this request.
Request ids
Every response names its request.
Header
What it says
X-Request-Id
Server generated id for this request, present on every response. Quote it to support; it is meaningless otherwise.
requestId: The same id as the X-Request-Id header. Quote it to support.
Business
The record the key belongs to.
The Business object
Field
Type
Always
Meaning
id
uuid
yes
name
string
yes
slug
string
yes
displayName
string
yes
email
string or null
yes
timezone
string
yes
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
string
yes
The ISO 4217 code every price is in; GBP for every business today. Prices are in pence.
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).
A branch of the business. Never the whole row: no coordinates, catchment, travel or hours columns.
Field
Type
Always
Meaning
id
uuid
yes
name
string
yes
address
string or null
yes
city
string or null
yes
postcode
string or null
yes
phone
string or null
yes
The branch's public contact, as shown to customers.
email
string or null
yes
website
string or null
yes
locationModel
fixed | mobile | both or null
yes
Whether the branch takes customers at its address, travels to them, or both. Null on a legacy row.
isPrimary
boolean
yes
isVisible
boolean
yes
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
string
yes
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
date-time
yes
GET
/api/v1/locations
locations:read
The business's branches, live ones only, the primary first.
Name
Where
Type
Required
Meaning
limit
query
integer (1 to 100, default 50)
no
Rows per page, 1 to 100 (a value above 100 is treated as 100). Example: 50
cursor
query
string
no
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
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.
A staff member's partner projection. Never email, phone, gender, pronouns, bio, specialisms, the not bookable reason or commission.
Field
Type
Always
Meaning
id
uuid
yes
The staffProfileId a booking names.
name
string
yes
The display name, else the first and last names; the identity a booking's staffName snapshot carries.
initials
string
yes
colour
string or null
yes
The calendar colour.
jobTitle
string or null
yes
profileImageUrl
string or null
yes
isBookable
boolean
yes
acceptsOnlineBookings
boolean
yes
deliveryMode
fixed | mobile | both
yes
homeLocationId
uuid or null
yes
locationIds
array of uuid
yes
Every branch the member works at, the home branch included.
serviceIds
array of uuid
yes
The services the member is assigned to perform.
createdAt
date-time
yes
GET
/api/v1/staff
staff:read
The roster's partner projection.
Name
Where
Type
Required
Meaning
limit
query
integer (1 to 100, default 50)
no
Rows per page, 1 to 100 (a value above 100 is treated as 100). Example: 50
cursor
query
string
no
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
locationId
query
uuid
no
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
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.
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.
The EligibleStaff object
The members who can perform one service, and where.
Field
Type
Always
Meaning
serviceId
uuid
yes
serviceName
string
yes
locationId
uuid or null
yes
The branch asked for; null when the answer covers every offering branch.
Rows per page, 1 to 100 (a value above 100 is treated as 100). Example: 50
cursor
query
string
no
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
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
locationId
query
uuid
no
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
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.
The bookable slots, computed live from the business's own calendar rules.
The AvailabilityDay object
The date mode: one day of slots.
Field
Type
Always
Meaning
date
date
yes
timezone
string
yes
serviceId
uuid
yes
slotMinutes
integer
yes
The step between candidate starts (15).
durationMinutes
integer
yes
The service's duration.
slots
array of AvailabilitySlot
yes
message
string or null
yes
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.
The AvailabilitySlot object
Field
Type
Always
Meaning
startTime
date-time
yes
The slot's start, UTC.
endTime
date-time
yes
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
string
yes
The start as the business sees it, HH:MM in the response's timezone.
staff
array of objects (id, name, locationId)
yes
Who can take this slot, and the branch each would take it at.
The AvailabilitySummary object
The summary mode: a status per day over the window.
Field
Type
Always
Meaning
from
date
yes
timezone
string
yes
serviceId
uuid
yes
days
array of objects (date, status)
yes
message
string or null
yes
The AvailabilityWindow object
The slot window mode (detail=slots): the slots per day over up to seven days.
Field
Type
Always
Meaning
from
date
yes
timezone
string
yes
serviceId
uuid
yes
slotMinutes
integer
yes
durationMinutes
integer
yes
days
array of objects (date, status, slots)
yes
GET
/api/v1/availability
availability:read
The bookable slots for a service, computed live from the same rules the business's own online booking calendar uses.
Name
Where
Type
Required
Meaning
serviceId
query
uuid
yes
The service. Must be active and offered at a branch customers can see; otherwise 404 NOT_FOUND. Example: 00000000-0000-4000-8000-0000000000e2
date
query
date
no
One day of slots (YYYY-MM-DD). Send date or from, never both. Example: 2026-10-06
from
query
date
no
The first day of a window (YYYY-MM-DD). Example: 2026-10-05
days
query
integer (1 to 31)
no
With from: the window's length. 1 to 31 for the summary (default 14); 1 to 7 with detail=slots (default 7). Example: 7
detail
query
summary | slots
no
With from: summary (a status per day, the default) or slots (the slots per day, days capped at 7). Example: slots
staffProfileId
query
uuid
no
Only this staff member's slots. Must be one of your staff; otherwise 404 NOT_FOUND. Example: 00000000-0000-4000-8000-0000000000a2
locationId
query
uuid
no
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
deliveryMode
query
fixed | mobile
no
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
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.
How the booking was made; api for a booking created through this API (the dashboard shows it as Partner).
paymentStatus
unpaid | deposit | paid | balance_due
yes
unpaid: nothing recorded. deposit: a deposit recorded, the balance owed. paid: paid in full at the price it was paid at; a refund may stand on record. balance_due: paid, then re priced above what was paid; the difference is owed (SEPT42J).
startTime
date-time
yes
endTime
date-time
yes
priceInPence
integer or null
yes
notes
string or null
yes
createdAt
date-time
yes
serviceId
uuid or null
yes
The service booked; null once that service is deleted (the serviceName snapshot remains).
staffProfileId
uuid or null
yes
The staff member; null once unassigned (the staffName snapshot remains).
locationId
uuid or null
yes
The branch; null on bookings made before branches were recorded.
updatedAt
date-time or null
yes
When the booking last changed; null until it first changes after creation. The updatedSince filter reads this, else createdAt.
cancelledAt
date-time or null
yes
When the booking was cancelled; null unless cancelled.
GET
/api/v1/bookings
bookings:read
The bookings in a start time window, oldest first.
Name
Where
Type
Required
Meaning
startDate
query
date
no
Inclusive lower bound on start_time. Defaults to 30 days ago. Example: 2026-10-05
endDate
query
date
no
Inclusive upper bound on start_time. Defaults to 90 days from now. Example: 2026-10-11
Only this status; all for every status. Absent: every status but cancelled. Any other word is refused with 400 VALIDATION_FAILED. Example: all
updatedSince
query
date-time
no
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
staffProfileId
query
uuid
no
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
locationId
query
uuid
no
Only this branch's bookings. A value that is not a UUID is refused with 400 VALIDATION_FAILED. Example: 00000000-0000-4000-8000-000000000c01
limit
query
integer (1 to 100, default 50)
no
Rows per page, 1 to 100 (a value above 100 is treated as 100). Example: 50
cursor
query
string
no
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
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.
Creates a booking on behalf of the calling business, confirmed and unpaid, recorded with the source api (the dashboard shows it as Partner).
Name
Where
Type
Required
Meaning
Idempotency-Key
header
string (1 to 255 characters)
no
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
customerName
body
string
yes
The customer name to record on the booking.
customerEmail
body
string or null
no
Optional customer email address; omit or use null when unavailable.
customerPhone
body
string or null
no
Optional customer phone number; omit or use null when unavailable.
serviceId
body
uuid
yes
The id of the service to book, from GET /api/v1/services.
staffProfileId
body
uuid
yes
The id of the staff member who will provide the service, from GET /api/v1/staff.
startTime
body
date-time
yes
The appointment start as an ISO 8601 timestamp, including the time zone offset or Z for UTC.
notes
body
string or null
no
Optional notes to record on the booking; omit or use null when none are needed.
locationId
body
uuid
no
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.
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.
Request
curl shows the document's example Idempotency-Key; send a fresh UUID with every new request, as the other two samples do.
curl -X POST "https://pro.pamprr.me/api/v1/bookings" \
-H "Authorization: Bearer $PAMPRR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 0b3f6c2e-8f0a-4d5b-9c1e-7a2b3c4d5e6f" \
-d '{"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"}'
curl shows the document's example Idempotency-Key; send a fresh UUID with every new request, as the other two samples do.
The same body on a retry with the same Idempotency-Key; the response carries Idempotent-Replayed: true and X-Original-Request-Id req_9a8b7c6d5e4f3a2b1c0d9e8f
Cancels a booking the way the business cancels one in its dashboard.
Name
Where
Type
Required
Meaning
id
path
uuid
yes
The booking id. Example: 00000000-0000-4000-8000-0000000000b3
Idempotency-Key
header
string (1 to 255 characters)
no
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
reason
body
string or null
no
Free text recorded on the booking and its event, up to 500 characters.
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.
Request
curl shows the document's example Idempotency-Key; send a fresh UUID with every new request, as the other two samples do.
Moves a booking to a new start time, and optionally to another staff member, the way the business does in its dashboard.
Name
Where
Type
Required
Meaning
id
path
uuid
yes
The booking id. Example: 00000000-0000-4000-8000-0000000000b3
Idempotency-Key
header
string (1 to 255 characters)
no
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
startTime
body
date-time
yes
The new start, in the future. The end follows from the booking's duration.
staffProfileId
body
uuid
no
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.
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.
Request
curl shows the document's example Idempotency-Key; send a fresh UUID with every new request, as the other two samples do.
When the client record last changed; null until it first changes after creation.
GET
/api/v1/clients
clients:read
The business's active clients by name.
Name
Where
Type
Required
Meaning
search
query
string (2 to 100 characters)
no
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
limit
query
integer (1 to 100, default 50)
no
Rows per page, 1 to 100 (a value above 100 is treated as 100). Example: 50
cursor
query
string
no
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
Creates a client record for the business, or returns the existing one.
Name
Where
Type
Required
Meaning
Idempotency-Key
header
string (1 to 255 characters)
no
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
name
body
string (1 to 200 characters)
yes
The name to record for the client, between 1 and 200 characters.
email
body
string or null
no
Stored lower cased; the duplicate check compares it case insensitively.
phone
body
string or null
no
Optional client phone number, up to 30 characters; omit or use null when unavailable.
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.
Request
curl shows the document's example Idempotency-Key; send a fresh UUID with every new request, as the other two samples do.
pamprr tells you when a booking, a client or a payment changes; signed, retried, logged.
Register an https endpoint in Settings, Operations, Webhooks, or through the endpoints below; copy its signing secret once; subscribe to every event or to a list. Each delivery is one signed POST carrying one event.
Events
Fourteen event types across bookings, clients and payments.
An endpoint subscribes to every event with ["*"] or to a list of catalogue names; ping is delivered to every endpoint regardless of its filter.
A booking event fires for a booking from any source: the online calendar, the dashboard, the app and this API alike.
A payment event is read from the ledger, so it fires for a deposit, a saved card charge, a till payment or a manual record; the booking it carries shows the paymentStatus after the entry.
A client event is read from the client book: a create, an update (a merge included) and an archive.
payment.refund_failed can arrive without a preceding payment.refunded: a refund reversed before its first pick up is read as its failure alone, and the event carries the amount and the booking on its own.
Type
When it fires
What data carries
booking.created
A booking was created, from any source: the online calendar, the dashboard, the app or this API.
data.booking is the booking as the API answers it, read when the event was picked up; source says where it came from.
booking.confirmed
A pending booking was confirmed.
data.booking with status confirmed.
booking.started
A booking was marked in progress.
data.booking with status in_progress.
booking.completed
A booking was marked completed.
data.booking with status completed; paymentStatus is the state at pick up.
booking.cancelled
A booking was cancelled by the customer, the business or the system.
data.booking with status cancelled and cancelledAt set, data.reason and data.cancelledBy.
booking.no_show
A booking was marked a no show.
data.booking with status no_show.
booking.rescheduled
A booking was moved to a new time.
data.booking at its new time and data.previous.startTime, the start it moved from.
client.created
A client was added to the client book, by any route.
data.client as the API answers it.
client.updated
A client's details changed, a merge included.
data.client after the change, with updatedAt set.
client.archived
A client was archived.
data.client and data.active false.
payment.succeeded
A payment for a booking was recorded in the ledger: a deposit, a saved card charge, a till payment or a manual record.
data.payment (the entry, the amount in pence, the currency, when it was recorded) and data.booking with the paymentStatus after the entry.
payment.refunded
A refund for a booking was recorded in the ledger.
data.payment with amountInPence the refunded amount, positive, and data.booking.
payment.refund_failed
A refund attempt for a booking failed.
data.payment without an id (no ledger entry), amountInPence the attempted amount or null, and data.booking.
ping
A test delivery, sent from the dashboard or by the test operation, regardless of the endpoint's filter and never retried.
data.endpointId and data.message.
Signing
Every delivery carries three Standard Webhooks headers; verify before you trust the body.
The signed content is the event id, a full stop, the timestamp, a full stop, the raw body bytes; the key is the base64 decoded secret after whsec_; the algorithm is HMAC SHA256; the signature is v1, then base64.
During the day after a rotation every delivery carries two signatures, one per secret, so a partner verifying with either passes.
The document's example deliveries are signed for real: each webhooks entry's example body, serialised compactly, verifies under its example headers with the example secret the create endpoint answers.
Header
What it says
webhook-id
The event id; the same on every attempt and replay of this event, so a partner can deduplicate.
webhook-timestamp
Unix seconds when this attempt was signed; refuse a delivery whose timestamp is more than five minutes from now.
webhook-signature
One or more signatures separated by spaces, each v1, then base64: HMAC SHA256 over id, a full stop, timestamp, a full stop, the raw body bytes, keyed by the base64 decoded secret after whsec_. Two during the day after a rotation. This example verifies the example body, serialised compactly, under the document's example secret.
Read webhook-id, webhook-timestamp and webhook-signature; refuse the delivery if any is missing.
Refuse it if webhook-timestamp is more than five minutes from now, either way: the replay window.
Compute HMAC SHA256 over id, a full stop, timestamp, a full stop, the raw body, with each secret you hold (the current one; during a rotation the old one too), and accept if any space separated v1 signature equals yours by a constant time comparison.
Deduplicate on webhook-id: at least once delivery means the same event can arrive twice.
Answer 2xx as fast as you can; do your work after acknowledging.
Verify a delivery
// npm install standardwebhooks
import { Webhook } from "standardwebhooks";
const webhook = new Webhook(process.env.PAMPRR_WEBHOOK_SECRET);
export async function handle(request) {
const body = await request.text();
const headers = {
"webhook-id": request.headers.get("webhook-id"),
"webhook-timestamp": request.headers.get("webhook-timestamp"),
"webhook-signature": request.headers.get("webhook-signature"),
};
let event;
try {
event = webhook.verify(body, headers);
} catch {
return new Response("bad signature", { status: 400 });
}
if (await alreadyHandled(event.id)) return new Response(null, { status: 200 });
await enqueue(event);
return new Response(null, { status: 200 });
}
At least once, usually within a minute of the change, retried over about two days.
Delivery is at least once: a retry, a replay or a send that died mid flight can repeat an event under the same webhook-id; treat a repeated id as already handled.
Apply events in occurredAt order, not arrival order: a retry, a burst or two runs overlapping can reorder deliveries.
A 2xx within ten seconds marks the delivery delivered. Anything else (a 3xx, which is never followed, a 4xx, a 5xx, a timeout) schedules the next attempt after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours: eight attempts over about 44 hours 36 minutes, then the delivery is a dead letter, visible in the log and replayable.
A 429 with Retry-After is honoured in place of the ladder's delay, up to twenty four hours.
A 410 marks the delivery failed and disables the endpoint at once with the reason gone; three days without a successful delivery disable it with the reason failing. Re enable it in Settings or with the update endpoint.
While an endpoint is disabled no events are queued for it: catch up by polling the API, then replay dead letters from the log.
Answer fast: acknowledge with a 2xx, then do the work. The log keeps thirty days of deliveries with every attempt's status code, duration, error class and the first kilobyte of the response.
Endpoints
Signed event deliveries to endpoints the business registers: the endpoints, their secrets, the test and the delivery log.
The WebhookEndpoint object
A business's webhook endpoint. Never the secret: it is shown once at creation and once at rotation.
Field
Type
Always
Meaning
id
uuid
yes
url
string
yes
The https URL deliveries are posted to, as stored (normalised).
description
string or null
yes
Your own label, up to 200 characters.
events
array of string
yes
["*"] for every event, or the catalogue names subscribed to. ping is always delivered.
status
enabled | disabled
yes
disabledReason
manual | failing | gone or null
yes
Why a disabled endpoint is disabled: manual (switched off), failing (three days without a successful delivery) or gone (it answered 410). Null while enabled.
payloadVersion
1
yes
The payload version pinned at creation. "1" today; a breaking change would ship as a new version chosen per endpoint.
createdAt
date-time
yes
updatedAt
date-time
yes
lastDeliveryAt
date-time or null
yes
When a delivery was last attempted, success or failure.
lastSuccessAt
date-time or null
yes
lastFailureAt
date-time or null
yes
secretRotatedAt
date-time or null
yes
When the secret was last rotated; null for a never rotated endpoint.
The WebhookDelivery object
One event's delivery to one endpoint, with its attempts. The event's payload is not repeated here.
Field
Type
Always
Meaning
id
uuid
yes
eventId
string
yes
The event id, the webhook-id header on every attempt.
eventType
WebhookEventType
yes
The catalogue of events an endpoint can subscribe to. ping is a test delivery and is sent regardless of the filter.
occurredAt
date-time
yes
When the event happened at pamprr (the envelope's occurredAt).
status
pending | delivered | failed | cancelled
yes
pending (waiting for its next attempt), delivered (a 2xx), failed (the eighth attempt failed, a 410, or a test ping that failed; replayable), cancelled (the endpoint was disabled or deleted while it waited; replayable).
attempts
integer
yes
Scheduled attempts made so far (the retry ladder's position); tests and replays do not count.
nextAttemptAt
date-time or null
yes
When a pending delivery is next attempted; null otherwise.
lastStatusCode
integer or null
yes
lastError
string or null
yes
deliveredAt
date-time or null
yes
failedAt
date-time or null
yes
createdAt
date-time
yes
When the delivery was created (the log's order).
attemptLog
array of WebhookDeliveryAttempt
yes
Every attempt, oldest first.
The WebhookEventType object
The catalogue of events an endpoint can subscribe to. ping is a test delivery and is sent regardless of the filter.
Field
Type
Always
Meaning
The WebhookDeliveryAttempt object
One HTTP attempt of a delivery.
Field
Type
Always
Meaning
attempt
integer
yes
The attempt's number in the delivery's log.
kind
scheduled | test | replay
yes
requestedAt
date-time
yes
durationMs
integer or null
yes
statusCode
integer or null
yes
The endpoint's HTTP status; null on a timeout, a refused URL or a network error.
error
string or null
yes
The error class: http_<status>, redirect (a 3xx is never followed), timeout, network, url_refused (the URL no longer resolves to a public address) or secret_unavailable; null on a 2xx.
responseExcerpt
string or null
yes
Up to 1 KiB of the endpoint's response body.
GET
/api/v1/webhooks
webhooks:manage
The business's live webhook endpoints, in creation order, the whole set (at most ten; no cursor).
Registers an https endpoint for signed deliveries and returns its signing secret ONCE.
Name
Where
Type
Required
Meaning
Idempotency-Key
header
string (1 to 255 characters)
no
Optional but recommended: the same rules as on create booking. For 24 hours the same key with the same request replays the first response, secret included, so a retried create never mints two endpoints; the same key with a different request is refused with 422 IDEMPOTENCY_KEY_REUSED. Example: 2c6f1a3e-5b7d-4e9f-8a1b-3c5d7e9f1a2b
url
body
string (12 to 2048 characters)
yes
https only; no credentials, no fragment; must resolve to a public address. pamprr's own hosts are refused.
events
body
array of string
no
["*"] (the default) or a non empty list of catalogue event names.
description
body
string or null
no
Optional label to help identify this endpoint, up to 200 characters.
The URL must use https, carry no credentials or fragment, and resolve to a public address (pamprr's own hosts and private networks are refused); the events filter is ["*"] for the whole catalogue or a non empty list of event names; the payload version is pinned at creation ("1" today).
A business may hold ten live endpoints.
Store the secret in your server's environment: it signs every delivery and is never shown again (rotate it if it is lost).
Send an Idempotency-Key so a retried request replays the first 201 with the same secret rather than creating a second endpoint.
Request
curl shows the document's example Idempotency-Key; send a fresh UUID with every new request, as the other two samples do.
Setting enabled false disables the endpoint with reason manual and cancels its pending deliveries: nothing is delivered while an endpoint is disabled, and an event that occurs during the disabled period is not delivered on re enabling (poll the lists with updatedSince to catch up, and replay from the delivery log).
Setting enabled true clears the reason and the failure clock.
Send an Idempotency-Key so a retried request replays the first outcome.
Request
curl shows the document's example Idempotency-Key; send a fresh UUID with every new request, as the other two samples do.
Stops every delivery to the endpoint: pending deliveries are cancelled, the delivery log is kept for thirty days, and the slot under the cap of ten is freed.
Name
Where
Type
Required
Meaning
id
path
uuid
yes
The endpoint id. Example: 00000000-0000-4000-8000-00000000e001
Idempotency-Key
header
string (1 to 255 characters)
no
Optional: a retried delete replays the first outcome. Example: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d
The endpoint id. Example: 00000000-0000-4000-8000-00000000e001
Idempotency-Key
header
string (1 to 255 characters)
no
Optional but recommended: a retried rotation replays the first outcome, secret included, rather than rotating twice. Example: 3e4f5a6b-7c8d-4e9f-8a0b-1c2d3e4f5a6b
The old secret keeps signing for twenty four hours: every delivery in that window carries two signatures (the new first, then the old, space separated in webhook-signature), so deploy the new secret at leisure and verify with either.
A second rotation inside the window discards the older previous secret; only two are ever live.
A rotation cannot be undone.
Send an Idempotency-Key so a retried request replays the first outcome with the same secret.
Request
curl shows the document's example Idempotency-Key; send a fresh UUID with every new request, as the other two samples do.
Sends a ping event to the endpoint at once, signed like any delivery, and answers 200 whether the endpoint accepted it or not: the outcome is data, not an error.
Name
Where
Type
Required
Meaning
id
path
uuid
yes
The endpoint id. Example: 00000000-0000-4000-8000-00000000e001
Idempotency-Key
header
string (1 to 255 characters)
no
Optional: a retried test replays the first outcome rather than pinging twice. Example: 5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f
The endpoint's delivery log, newest first: each row carries its event's type and time, the delivery's state, the ladder position and every attempt with its status code, error class and a response excerpt of up to 1 KiB.
Name
Where
Type
Required
Meaning
id
path
uuid
yes
The endpoint id. Example: 00000000-0000-4000-8000-00000000e001
status
query
pending | delivered | failed | cancelled
no
Only deliveries in this state. An unknown value is 400 VALIDATION_FAILED. Example: failed
eventType
query
WebhookEventType
no
Only deliveries of this event type. An unknown name is 400 VALIDATION_FAILED. Example: booking.cancelled
since
query
date-time
no
Only deliveries created at or after this moment (ISO 8601). A value that does not parse is 400 VALIDATION_FAILED. Example: 2026-09-25T00:00:00Z
limit
query
integer (1 to 100, default 50)
no
Rows per page, 1 to 100 (a value above 100 is treated as 100). Example: 50
cursor
query
string
no
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: eyJ2IjoyLCJsIjoid2ViaG9vay1kZWxpdmVyaWVzIiwiayI6WyIyMDI2LTA5LTI1VDEwOjE2OjAwLjAwMFoiLCIwMDAwMDAwMC0wMDAwLTQwMDAtODAwMC0wMDAwMDAwMGQwMDEiXSwiZiI6ImUzYjBjNDQyIn0
Attempts a delivered, failed or cancelled delivery once more, at once and outside the retry ladder: the same event bytes under the same webhook-id, with a fresh timestamp and signature.
Name
Where
Type
Required
Meaning
id
path
uuid
yes
The endpoint id. Example: 00000000-0000-4000-8000-00000000e001
deliveryId
path
uuid
yes
The delivery id, from the delivery log. Example: 00000000-0000-4000-8000-00000000d001
Idempotency-Key
header
string (1 to 255 characters)
no
Optional: a retried replay replays the first outcome rather than attempting twice. Example: 7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d
A 2xx marks the delivery delivered; anything else records the attempt and leaves the status as it was.
A pending delivery is refused with 409 WEBHOOK_DELIVERY_PENDING (it will be attempted on schedule); a disabled endpoint with 409 WEBHOOK_ENDPOINT_DISABLED.
The partner's recovery from a dead letter.
Send an Idempotency-Key so a retried request replays the first outcome.
Request
curl shows the document's example Idempotency-Key; send a fresh UUID with every new request, as the other two samples do.
One envelope for every event; data carries the same projections the API answers.
id is the event id and the webhook-id; type the catalogue name; apiVersion the path prefix the shapes belong to; payloadVersion the endpoint's pinned version, "1" today; occurredAt the source row's own time; business.id lets a partner serving several pamprr businesses route.
The body is serialised once when the event is picked up and sent byte identical on every attempt and replay: data is the state at pick up, within a minute of the change; a later change is its own event with its own occurredAt.
Within a payload version everything is additive: fields and event types are added, never removed or renamed; ignore what you do not know. A breaking change would ship as a new version chosen per endpoint, with the old kept for at least six months.
The WebhookEvent object
The envelope of every delivery: one document per event, serialised once when the event was picked up and sent byte identical on every attempt and replay, so the signature covers the same bytes each time.
Field
Type
Always
Meaning
id
string
yes
The event id, also the webhook-id header; deduplicate on it, since delivery is at least once.
type
WebhookEventType
yes
The catalogue of events an endpoint can subscribe to. ping is a test delivery and is sent regardless of the filter.
apiVersion
v1
yes
The path prefix whose shapes data carries.
payloadVersion
1
yes
The endpoint's pinned payload version; everything within it is additive.
occurredAt
date-time
yes
The source row's own time, not the pick up time. Apply events in this order, not arrival order.
business
object
yes
The business the event belongs to, so a partner serving several pamprr businesses can route.
data
one of BookingEventData, BookingCancelledEventData, BookingRescheduledEventData, ClientEventData, ClientArchivedEventData, PaymentEventData, PingEventData
yes
The event's data, one shape per type; each webhooks entry below names its shape.
The BookingEventData object
booking.created, booking.confirmed, booking.started, booking.completed and booking.no_show: the booking as the API answers it, read when the event was picked up.
Field
Type
Always
Meaning
booking
Booking
yes
The BookingCancelledEventData object
booking.cancelled: the booking (status cancelled, cancelledAt set), the reason given and who cancelled.
Field
Type
Always
Meaning
booking
Booking
yes
reason
string or null
yes
The reason given at cancellation, or null when none was.
cancelledBy
consumer | business | system or null
yes
Who cancelled: the customer, the business, or pamprr itself; null when the record does not say.
The BookingRescheduledEventData object
booking.rescheduled: the booking at its new time and the start it moved from.
Field
Type
Always
Meaning
booking
Booking
yes
previous
object
yes
The ClientEventData object
client.created and client.updated: the client as the API answers it.
Field
Type
Always
Meaning
client
Client
yes
The ClientArchivedEventData object
client.archived: the client and the fact of the archive.
Field
Type
Always
Meaning
client
Client
yes
active
false
yes
Always false: the client is archived.
The PaymentEventData object
payment.succeeded, payment.refunded and payment.refund_failed: the ledger entry and the booking it belongs to, whose paymentStatus is the state after the entry.
Field
Type
Always
Meaning
payment
object
yes
booking
Booking
yes
The PingEventData object
ping: a test delivery sent from the dashboard or by the API, regardless of the endpoint's filter, never retried.
{
"id": "evt_00000000000000000000000d",
"type": "ping",
"apiVersion": "v1",
"payloadVersion": "1",
"occurredAt": "2026-10-06T08:31:12.000Z",
"business": {
"id": "00000000-0000-4000-8000-00000000b001"
},
"data": {
"endpointId": "00000000-0000-4000-8000-00000000e001",
"message": "A test delivery from pamprr."
}
}
Notifications and partner bookings
What a partner action tells the customer, and how the business sees it.
A booking created through the API is recorded with the source api and shows as Partner in the business's diary.
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.
Cancelling through the API never refunds a deposit or charges a late cancellation fee; refunds are made by the business in its dashboard. Anyone on the waiting list for a freed slot is notified either way.
Versioning and deprecation
The version is the path prefix; changes are additive; a breaking change carries at least six months' notice.
Fields, headers, parameters, enum values and endpoints are added, never removed or renamed, without notice.
A change that would break an integration (a removed field, a renamed header, a changed meaning) is announced in the changelog at least six months before it happens.
The notice period is only ever extended, never shortened.
The document's version tracks additive releases.
Host https://pro.pamprr.me; every path begins /api/v1. The document's version today: 1.2.0.
Changelog
Dated entries, newest first.
1.2.0Webhooks
Outbound webhooks: fourteen event types across bookings, clients and payments, delivered as signed POSTs (Standard Webhooks headers, HMAC SHA256, a day of dual signing on rotation), retried over about two days and logged for thirty; the Webhooks section of this page and the OpenAPI 3.1.1 document's native webhooks entries, one signed example per type.
Nine operations under the Webhooks tag on the scope webhooks:manage, now live: the endpoints (list, create, read, update, delete), the secret rotation, the test delivery, the delivery log and the replay; three new codes, WEBHOOK_LIMIT_REACHED, WEBHOOK_ENDPOINT_DISABLED and WEBHOOK_DELIVERY_PENDING.
1.1.0The first published reference
This page, its markdown twin at /developers.md, and the OpenAPI 3.1.1 document with an example on every parameter, request body and response.
The surface at launch: the business record, locations, staff, services and the eligible staff for one, the availability search, bookings (list, create, read, cancel, reschedule) and clients (list, create, read), on the foundations of request ids, the rate limit headers, scoped keys, cursor pagination and idempotency keys.
The OpenAPI document
The machine readable description of everything on this page, with the same examples.
GET /api/businesses/search returns business rows by default and one row per visible branch with rows=branches. For branch rows, serviceCount, priceRange and footer.startingPriceInPence describe services offered at that branch through service_locations: active, undeleted services only, excluding add ons. The count and both prices use the same population, across all categories even when a category filter selects the row. An empty branch has serviceCount 0, priceRange { min: null, max: null } and footer.startingPriceInPence null. Business rows retain business-wide figures, including when a nearby branch supplies their address; a legacy row with branch null also uses business figures. Public discovery needs no partner API key. Responses are private, no-store; their catalogue snapshot is shared for 60 seconds with immediate tag expiry after public edits. Branch aggregates and footer calculation add no database reads. The next available slot is omitted because the existing availability summary is live and is absent from both display snapshots. Open state describes cached opening hours evaluated at request time, not capacity. The partner API conventions above do not apply to this consumer endpoint. Rating fields on the row and footer use the same grain. For rows=branches with a non-null branch, only published reviews whose booking belongs to that branch and business qualify. The booking branch is authoritative, not the review's denormalised branch pointer. Business rows and legacy rows with branch null retain all published business reviews, including reviews without an attributable booking. A branch with none has reviewCount 0, row.averageRating 0 for compatibility and footer.averageRating null. Browse renders "No reviews yet at this branch". Rating sorts use branch averages and counts, with unrated rows last in both directions.
Business or branch search row. With rows=branches and a non-null branch, services and ratings describe that branch. Business rows and legacy branch-null rows retain business figures.
Field
Type
Always
Meaning
serviceCount
integer
yes
For a branch row, the number of active, undeleted services offered at that branch through service_locations, excluding add ons. Zero when none qualify. Business rows retain their existing count across visible branches, including add ons; a service offered at multiple branches counts once at business grain.
priceRange
object
yes
Minimum and maximum current listed prices in GBP pence from the same population as serviceCount. Branch rows exclude add ons; business rows retain their existing range including add ons. Both endpoints are null without qualifying services. Conditional discounts and vouchers are not applied.
averageRating
number (0 to 5)
yes
Published review mean rounded to one decimal. For rows=branches with a non-null branch, only published reviews whose booking belongs to that branch and business qualify. The booking branch is authoritative, not the review's denormalised branch pointer. Business rows and legacy rows with branch null retain all published business reviews, including reviews without an attributable booking. Zero without published reviews for compatibility; the footer uses null.
reviewCount
integer
yes
Number of published reviews at the row's grain. For rows=branches with a non-null branch, only published reviews whose booking belongs to that branch and business qualify. The booking branch is authoritative, not the review's denormalised branch pointer. Business rows and legacy rows with branch null retain all published business reviews, including reviews without an attributable booking. Zero without qualifying reviews.
The BusinessCardFooter object
Display data from the catalogue snapshot, added in both search row modes. No next slot is supplied.
Field
Type
Always
Meaning
averageRating
number (0 to 5) or null
yes
Published review mean rounded to one decimal. For rows=branches with a non-null branch, only published reviews whose booking belongs to that branch and business qualify. The booking branch is authoritative, not the review's denormalised branch pointer. Business rows and legacy rows with branch null retain all published business reviews, including reviews without an attributable booking. Null without qualifying published reviews; never falls back to the business figure for an unrated branch.
reviewCount
integer
yes
Number of published reviews at the row's grain. For rows=branches with a non-null branch, only published reviews whose booking belongs to that branch and business qualify. The booking branch is authoritative, not the review's denormalised branch pointer. Business rows and legacy rows with branch null retain all published business reviews, including reviews without an attributable booking. Zero without qualifying reviews.
distanceMiles
number or null
yes
The existing selected row distance in miles rounded to one decimal. Null without a resolved request position or usable business coordinates.
startingPriceInPence
integer or null
yes
Minimum current listed service price in GBP pence. For rows=branches with a non-null branch, only services offered at that branch through service_locations qualify. Business rows, and legacy rows with branch null, use the minimum across visible branches of the business. Active, undeleted services only, excluding add ons in both modes. Null without a qualifying service. A listed offer uses its current service price; conditional discounts and vouchers are not applied.
openNow
boolean or null
yes
Schedule state at request time in Europe/London. Uses the selected branch hours with business fallback, or the primary overlay without a selected branch. Mobile businesses use mobile hours; fixed and both use fixed hours. Per day hours override legacy working days and opening and closing times. Includes yesterday's overnight interval. Opening is inclusive and closing exclusive; equal times mean closed. Null when incomplete or malformed hours prevent a conclusion. This is not bookable capacity.
The ProfileReviewSummary object
Returns published reviews and their figures from the cached profile snapshot. Omit branchId for all business reviews. Supply branchId for reviews attributed through bookings to that visible branch; an empty branch returns reviews [], totalCount 0 and averageRating null. Unknown, foreign, hidden or deleted branches return 404, never business figures. The snapshot is cached for 60 seconds with immediate expiry after public edits. Branch selection filters that snapshot without another database query or a branch-specific cache key. HTTP responses are private, no-store.
Field
Type
Always
Meaning
averageRating
number (1 to 5) or null
yes
One-decimal mean of published reviews for the selected branch, or the whole business when branchId is omitted. Null when there are no reviews.
totalCount
integer
yes
Published review count for the selected branch, or the whole business when branchId is omitted. Zero when there are no reviews.
reviews
array of objects (id, rating, reviewText, businessResponse, publishedAt, createdAt, reviewerName)
yes
Published reviews at the selected grain, newest publication first. Reviewer surnames are reduced to initials.
Support
Quote the request id.
Every response carries X-Request-Id; quote it.
Write through the contact page, or through the business that minted your key, whose owner can reach pamprr from the dashboard's help centre.