Introduction

The Service API is an HTTP API for your restaurant’s reservations and guests. You can read them, and you can book, hold, change and cancel.

The restaurant words this site uses without ceremony — a cover, a service, a shift limit, a published booking — are defined in the Glossary.

It is designed for restaurants and the tools they use — custom websites, internal dashboards, CRMs, analytics pipelines, automations, and booking funnels built on top of Service — that want programmatic access to their own reservation and guest data.

Good to know

• Self-serve setup. Create API keys and register webhook endpoints yourself from the back office (Settings → Developers) — no request needed.
• What a key may do is chosen when it is minted. A new key reads and nothing else; booking, overriding a rule and reading guests are separate scopes the restaurant grants one at a time.
• No public sandbox. There is one production base URL and every key is live. A booking you create is real, and so is a cancellation — there is nowhere to rehearse one but a restaurant you own.
• Writes fire webhooks. A create or a cancel emits the same events a booking taken in the back office does, so your own call can be the thing that exercises your handler.

Base URL

All requests go to a single, dedicated host over HTTPS:

https://api.useservice.app

Every endpoint lives under the stable /v1 path prefix, for example:

GET  https://api.useservice.app/v1/reservations
POST https://api.useservice.app/v1/reservations
GET  https://api.useservice.app/v1/guests

What you can do

• Book — create a reservation, change one, and cancel one. Every create carries an Idempotency-Key, so a retry after a timeout resolves to the same booking instead of a second one.
• Hold a slot — take a table off sale while a guest finishes paying or deciding, then convert the hold into the booking or hand it back. A hold is not a reservation and does not appear among them.
• Reservations — list and filter reservations, retrieve a single reservation (with its table assignments and guest), and read a reservation’s lifecycle event history.
• Availability and policy — ask which times are bookable on a date or across a month, read the restaurant’s booking rules, and list its seating areas.
• Guests — list and search guests by phone, email, or free-text query, and retrieve a single guest with contact details, consent flags, and visit stats.
• Waitlist — read the queue of guests waiting for a table. It is readable only: an entry is joined from the widget or the back office, not from here.
• Webhooks — subscribe to signed, real-time events for the reservation lifecycle, holds, and guest and feedback events. See Webhooks.

Guests are read-only. A booking you create names its guest, and Service resolves or creates the record behind it; there is no endpoint that edits a guest directly.

Conventions at a glance

Area	Convention
Transport	HTTPS only, JSON request/response bodies
Auth	Authorization: Bearer sk_live_… — a per-restaurant API key
Versioning	Date-based Service-Version header, pinned per key
IDs	Opaque, prefixed strings (resv_…, gst_…) — never assume a format beyond the prefix
Timestamps	ISO-8601 with the restaurant’s UTC offset (e.g. 2026-06-27T19:30:00+02:00)
Lists	{ "object": "list", "data": [...], "has_more": true } — see Pagination
Errors	{ "error": { "type", "code", "message", "param"?, "doc_url" } } (param only when a parameter is at fault) — see Errors
Writes	Idempotency-Key, required on every create and optional on the rest — see Errors
Permissions	Per-key scopes, granted at creation and never widened
Objects	Every resource carries an object field ("reservation", "guest", "list", …)

Response shape

Single resources are returned as a flat JSON object with an object discriminator:

{
  "object": "reservation",
  "id": "resv_8xKQ2m4Vd0pErJ7sN1aZ9bQ",
  "status": "confirmed",
  "party_size": 4,
  "service_date": "2026-06-27",
  "starts_at": "2026-06-27T20:00:00+02:00",
  "created_at": "2026-06-20T11:04:18+02:00",
  "updated_at": "2026-06-25T09:12:55+02:00"
}

Collections are wrapped in a list envelope:

{
  "object": "list",
  "data": [ { "object": "reservation", "id": "resv_…" } ],
  "has_more": true
}

Next steps

1. Read Authentication, pick the scopes you need, and get a key.
2. Skim Pagination and Errors — the errors page also covers idempotency and what a refused booking looks like.
3. Follow a use case end to end: Build a booking funnel walks availability through to the create, and Hold a slot covers claiming a table while a package is assembled. Three go further: Book past the rules, Keep your system in sync and Take a deposit.
4. Browse the full API reference, or grab the OpenAPI spec to generate an SDK or import it into Postman.
5. Set up Webhooks to react to changes in real time.