Reservations
Book a restaurant table for a person, over REST. Layout handles the booking system, fees and proof. You collect the person's booking account phone and the code its provider texts them.
Overview
- Search for places and times: POST /v1/reservations/search.
- Book a time: POST /v1/reservations. It books at once when it can.
- Respond while
nextis set: POST /v1/reservations/:id/respond.
Layout books through OpenTable and Resy, on the person's own account. Layout sends the person no text in this flow: the only message they get is the provider's own code.
Base URL https://api.layout.link. Call with your secret key (see Authentication). Available in early access: contact us. Until your application has access, every route answers 403 not_enabled.
Tables with a deposit, a cancellation fee or a card hold need a second grant: paid tables. Ask for it with early access. Without it, Layout reads the table's terms and then ends the booking failed with paid_table_unavailable. Nothing is booked. Sandbox keys always have it.
Who it's for
- An agent you text. Send
next.askin the thread, and send the person's reply to respond. - An app with its own UI. Render each
next.kindnatively, and send what the person enters to respond.
Connect a booking account
Layout books on the person's own OpenTable or Resy account, so it signs in once with the phone on that account and the code the provider texts. Connect at signup, or inside the first booking.
- Consent. Every
phonegoes withconsent: true: you attest the person gave an explicit yes to linking their booking account and booking through your app. Layout records it. - One code per application. Your first connect to a person's account always needs the provider's code, even if they connected it elsewhere. After that, bookings need none.
- The phone is the mobile number on the person's booking account: US or Canadian, E.164 (
+15551234567). Anything else is422 invalid_request. It need not be the number on their Layout user, and the Layout verify is not needed. - No account with that provider: the start still answers
202, but no code arrives, and any code sent is422 wrong_code. Ask the person to create one in the provider's app, then connect again. Layout never says whether an account exists. - Connected on another number:
409 account_exists. The person disconnects it in their Layout account first.
POST /v1/users/:id/connections
curl https://api.layout.link/v1/users/usr_4b8e9a01c2d3/connections \
-H "Authorization: Bearer $LAYOUT_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "provider": "opentable", "phone": "+15551234567", "consent": true }'
| Field | Required | Notes |
|---|---|---|
provider | This, or placeId, never both | opentable or resy. A sandbox key: sandbox. |
placeId | This, or provider, never both | A place from search. Connects the system it books through. |
phone | Yes | The number on the person's booking account. |
consent | Yes | true. |
202 Accepted
{
"provider": "OpenTable",
"state": "pending",
"next": { "kind": "connect_code", "ask": "OpenTable just texted you a code. What is it?", "codeFrom": "sms" }
}
202: a sign-in started, and the provider texts its code. 200: already connected for your application, nothing sent.
| Connection | Notes |
|---|---|
provider | The booking system's name, to show. |
state | pending (waiting on next), connected, or needs_reconnect (send the phone and consent again). |
next | null, or connect_code or connect_email, as in Respond. |
POST /v1/users/:id/connections/:provider/respond
Send exactly one of code, email or action: "resend". :provider is opentable, resy or sandbox. Answers 200 with the Connection.
curl https://api.layout.link/v1/users/usr_4b8e9a01c2d3/connections/opentable/respond \
-H "Authorization: Bearer $LAYOUT_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "code": "482913" }'
GET /v1/users/:id/connections
{ "connections": [Connection] }: each system the person is connected to, or signing in to, for your application.
DELETE /v1/users/:id/connections/:provider
Withdraws your consent and drops your application's sign-in. Answers 204. Layout keeps the account only while another application or Layout itself still uses it. Nothing is sent to the provider, and the person's bookings stand.
POST /v1/reservations/search
Places with open tables, and their times. Works with sandbox and live keys. With a live key, one search at a time per application: a second while one runs is 429 rate_limited.
curl https://api.layout.link/v1/reservations/search \
-H "Authorization: Bearer $LAYOUT_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"lat": 37.7793,
"lng": -122.4193,
"date": "2026-11-20",
"time": "19:00",
"partySize": 2,
"userId": "usr_4b8e9a01c2d3"
}'
| Field | Required | Notes |
|---|---|---|
near | This, or lat and lng | A city, neighbourhood or address, up to 120 characters. |
lat, lng | These, or near | Numbers, sent together. Used over near when both are sent. |
date | Yes | YYYY-MM-DD. Not past, and at most 90 days out. |
time | No | HH:MM, 24-hour, the restaurant's local time. Times nearest it come first. |
partySize | Yes | A whole number, 1 to 50. |
query | No | A restaurant name or kind of food, up to 100 characters. |
userId | No | The person. Adds ready to each place. |
radiusMiles | No | 1 to 25. Default 10. |
200 OK
{
"places": [
{
"id": "rp_eyJwIjoic2FuZGJveCIsInYiOiJkaW5lci5BbWVyaWNhL0xvc19BbmdlbGVzIn0",
"name": "Sandbox Diner",
"area": "Sandbox",
"address": "100 Sandbox Street",
"phone": "+15555550100",
"lat": 37.7813,
"lng": -122.4193,
"timeZone": "America/Los_Angeles",
"bookedThrough": "Sandbox",
"ready": false,
"times": [
{ "slotId": "rs_eyJwIjoic2FuZGJveCIs...", "localTime": "2026-11-20T19:00", "partySize": 2, "tableType": null },
{ "slotId": "rs_eyJwIjoic2FuZGJveCIs...", "localTime": "2026-11-20T18:30", "partySize": 2, "tableType": null }
]
}
],
"incomplete": false,
"unreadSources": []
}
| Field | Notes |
|---|---|
places | Up to 20. Empty when nothing is open. |
incomplete, unreadSources | true, with the booking systems Layout could not read, such as ["Resy"], when the list may be missing places. When none could be read, the answer is 503 unavailable. |
id | The place. Opaque. |
name, area | Show both, so the person can tell places apart. |
address, phone | As the provider states them, or null. |
timeZone | The place's IANA zone. Every localTime is on this clock. |
bookedThrough | The booking system's name, to show. Never branch on it. |
ready | Only with userId. true when the person is connected for your application and books without a sign-in. Absent when Layout could not tell. |
times | Up to 10, nearest to time first. A place with no time that night gets the next nights' times. |
slotId | The time to book. Send it exactly as given. It also carries the place's name, address and phone, so a new booking shows them. |
localTime | YYYY-MM-DDTHH:MM at the place. Show the date: it can be a later night than date. |
tableType | The restaurant's name for the seating, or null. |
POST /v1/reservations
Books the time. Connected, it books a free table at once, or asks confirm for a paid one. Not connected, it answers pending with a sign-in step.
curl https://api.layout.link/v1/reservations \
-H "Authorization: Bearer $LAYOUT_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7f3c2a9e-resv-1" \
-d '{
"userId": "usr_4b8e9a01c2d3",
"slotId": "rs_eyJwIjoic2FuZGJveCIs...",
"reference": "order-1182"
}'
| Field | Required | Notes |
|---|---|---|
userId | Yes | The person, from Provisioning users. |
slotId | Yes | From search. A sandbox key books only sandbox places, and a live key only real ones. |
Idempotency-Key header, or idempotencyKey | Yes | Up to 200 characters, one per booking. Send both and the body's idempotencyKey is used: the header is ignored. The same key answers the same reservation with 200 and sends nothing again. The same key with another slot is 409 idempotency_conflict. |
reference | No | Your own string, 1 to 200 characters, echoed on the Reservation. |
phone, consent | No | Connects the person in the same call when they are not connected. See Connect a booking account. |
201 Created
{
"id": "rsv_5d0c2b1e8a4f4c3e9b7a2f1e0d9c8b7a",
"state": "pending",
"version": 1763143202118,
"createdAt": "2026-11-14T18:00:02.118Z",
"expiresAt": "2026-11-14T18:30:02.118Z",
"reference": "order-1182",
"place": { "id": "rp_eyJwIjoic2FuZGJveCIsInYiOiJkaW5lci5BbWVyaWNhL0xvc19BbmdlbGVzIn0", "name": "Sandbox Diner", "address": "100 Sandbox Street", "phone": "+15555550100", "timeZone": "America/Los_Angeles", "bookedThrough": "Sandbox" },
"localTime": "2026-11-20T19:00",
"partySize": 2,
"terms": null,
"confirmationNumber": null,
"next": { "kind": "connect", "ask": "What's the phone number on your Sandbox account?" }
}
The Reservation
Book, respond, cancel, get and list all answer with it.
| Field | Notes |
|---|---|
id | rsv_ and 32 characters. Opaque. |
state | See below. |
version | An integer that grows when the reservation changes. It never decreases, and two can tie. |
createdAt | ISO 8601, UTC. |
expiresAt | Only while pending: 30 minutes after it was made, or 15 minutes before the table if sooner. Past it, the reservation ends failed with expired. Otherwise null. |
reference | Your reference, or null. |
place | id, name, address, phone, timeZone, bookedThrough. All are there from the start, as search showed them. Once Layout reads the table, the provider's own replace them. address and phone are null when neither search nor the provider gave them. |
localTime, partySize | The time at the place, and the party. |
terms | null until Layout has read the table. See below. |
confirmationNumber | The provider's confirmation number once the booking is proven: booked, cancelling, cancelled, and unresolved when the provider gave one. Otherwise null. |
next | null, or the step Layout waits on. See Respond. |
failure | Only when failed or unresolved: code and message. See Failure codes. |
terms | Notes |
|---|---|
deposit | Money. |
cancellationFee | Money. The whole party's fee. |
freeCancelUntil | An ISO 8601 instant, or null. |
perGuest | true when the fee is charged per guest. |
card | { "brand", "last4" }, the card on the person's booking account, or null. |
Money is { "cents": 5000, "currency": "USD" }, or { "unknown": true, "currency": "USD" } when Layout could not read it.
state | Meaning | What you do |
|---|---|---|
pending | Waiting on next. | Respond before expiresAt. With next: null, respond with action: "retry". |
booking | Layout is booking. | Wait for the webhook, or get it. |
booked | Confirmed, and seen on the person's own account. | Tell the person. |
checking | Layout is reading the person's account to learn whether it booked. | Never retry or book again. Wait for the webhook, or get it later. |
unresolved | Final. Layout could not confirm the outcome. See failure. | Ask the person to check their provider app. Do not book again blindly. |
failed | Not booked. See failure. | Show failure.message. |
cancelling | Layout is cancelling. | Wait. |
cancelled | Cancelled. | Nothing. |
POST /v1/reservations/:id/respond
Answers next. Send userId and exactly one of code, email, confirm, phone (with consent) or action. An empty answer is 400 invalid_request.
next.kind | What happened | Send |
|---|---|---|
connect | The person is not connected for your application. | Ask for the phone on their booking account, then { "userId", "phone", "consent": true } |
connect_code | The provider sent a code. codeFrom is sms or email. | { "userId", "code" } |
connect_email | The provider asks for the account's email. | { "userId", "email" } |
confirm | A deposit, a cancellation fee or a card hold. | Show the terms, then { "userId", "confirm": next.confirmId } |
add_card | The table needs a card, and the booking account has none. | Send them to next.url, the provider's own page (none in sandbox). When they say done, { "userId", "action": "retry" } |
askis a sentence Layout writes from the terms. Show or text it as is, or render your own from everytermsfield, the card included.action: "resend"asks the provider for a new code to the same number.action: "retry"runs the pending step again: afteradd_card, or after a503.phonestarts a new sign-in, even over one waiting on a code.codeis a string, 4 to 8 digits. Spaces and hyphens are ignored.- A respond that arrives after the reservation moved on answers it as it stands, with
200.
curl https://api.layout.link/v1/reservations/rsv_5d0c2b1e8a4f4c3e9b7a2f1e0d9c8b7a/respond \
-H "Authorization: Bearer $LAYOUT_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "userId": "usr_4b8e9a01c2d3", "code": "000000" }'
200 OK
{
"id": "rsv_5d0c2b1e8a4f4c3e9b7a2f1e0d9c8b7a",
"state": "booked",
"version": 1763143300502,
"createdAt": "2026-11-14T18:00:02.118Z",
"expiresAt": null,
"reference": "order-1182",
"place": {
"id": "rp_eyJwIjoic2FuZGJveCIsInYiOiJkaW5lci5BbWVyaWNhL0xvc19BbmdlbGVzIn0",
"name": "Sandbox Diner", "address": "100 Sandbox Street", "phone": "+15555550100",
"timeZone": "America/Los_Angeles", "bookedThrough": "Sandbox"
},
"localTime": "2026-11-20T19:00",
"partySize": 2,
"terms": {
"deposit": { "cents": 0, "currency": "USD" }, "cancellationFee": { "cents": 0, "currency": "USD" },
"freeCancelUntil": null, "perGuest": false, "card": null
},
"confirmationNumber": "SBX9F2C4A71B0D3",
"next": null
}
A confirm step, at Sandbox Steakhouse:
"terms": {
"deposit": { "cents": 0, "currency": "USD" },
"cancellationFee": { "cents": 5000, "currency": "USD" },
"freeCancelUntil": "2026-11-20T03:00:00.000Z",
"perGuest": true,
"card": { "brand": "VISA", "last4": "4242" }
},
"next": {
"kind": "confirm",
"ask": "Sandbox Steakhouse, Fri, Nov 20 at 7:00 PM, 2 people. Cancel after Nov 19 at 7:00 PM and Sandbox charges your Visa ending 4242 on Sandbox $25 per person ($50.00). Book it?",
"confirmId": "cf_b_..."
}
POST /v1/reservations/:id/cancel
The body is empty, or { "userId" }, which must then name the reservation's person. Answers with the Reservation.
- Booked, no fee: cancelled once the person's account no longer lists it.
- Booked, with a fee or deposit: it stays
bookedwithnext.kindconfirm. Show the terms, then respond withconfirm. A later GET showsnext: nulluntil you cancel again. - Pending: ends
failedwithwithdrawn. Nothing is sent. - Booking or checking:
409 not_cancellable_yet. Nothing is sent. Cancel once it settles. - Anything else: the Reservation as it stands, with
200.
The cancel ask names the fee and the card. Before the free-cancel time it says so first:
"ask": "Sandbox lists free cancellation until Nov 19 at 7:00 PM. After that it may charge your Visa ending 4242 on Sandbox the $50.00 cancellation fee. Cancel your Sandbox Steakhouse table on Fri, Nov 20 at 7:00 PM?"
curl https://api.layout.link/v1/reservations/rsv_5d0c2b1e8a4f4c3e9b7a2f1e0d9c8b7a/cancel \
-H "Authorization: Bearer $LAYOUT_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{}'
Get and list
GET /v1/reservations/:id
curl https://api.layout.link/v1/reservations/rsv_5d0c2b1e8a4f4c3e9b7a2f1e0d9c8b7a \ -H "Authorization: Bearer $LAYOUT_SECRET_KEY"
Answers with the Reservation. ?userId= is optional and must name its person. On a checking reservation it may read the person's account first.
GET /v1/reservations
Your application's reservations for one person, in the key's environment, newest first, 20 a page. userId is required.
curl "https://api.layout.link/v1/reservations?userId=usr_4b8e9a01c2d3" \ -H "Authorization: Bearer $LAYOUT_SECRET_KEY"
200 OK
{ "reservations": [ { "id": "rsv_5d0c2b1e8a4f4c3e9b7a2f1e0d9c8b7a", "state": "booked", ... } ], "nextCursor": null }
When nextCursor is set, send it as cursor for the next page.
Webhook
reservation.updated is sent when a reservation's state or next changes, including when it ends unresolved. Add it to a subscription's events. Signed and retried like order events: see Webhooks. The payload is in Event types.
It cannot be fired as a test event. To see one, book a sandbox place.
Errors
The usual shape (see Error shape). Where marked, the answer also carries reservation, or on a connections route connection, as it stands:
409 Conflict
{
"error": { "code": "terms_changed", "message": "The table's terms changed since they were shown. Show the person the new terms and confirm again with the new confirmId." },
"reservation": { "id": "rsv_5d0c2b1e8a4f4c3e9b7a2f1e0d9c8b7a", "state": "pending", ... }
}
| Code | Status | What it means, and what to do |
|---|---|---|
invalid_request | 400, 422 | 400: the body is not a JSON object, a field is missing or malformed, or respond had not exactly one answer. 422: the phone is not a US or Canadian mobile number; ask for the mobile number on the booking account. |
not_enabled | 403 | Your application does not have early access. Contact us. |
not_found | 404 | No such user, reservation or connection for your application and key. |
idempotency_conflict | 409 | The key was used for another slot. Send a new key. |
wrong_step | 409 | Marked. Not what next asks for. Send what it asks. |
terms_changed | 409 | Marked. The terms changed, or the confirmId is stale. Show the new terms, then confirm with the new confirmId. |
code_expired | 409 | Marked. No sign-in is waiting for a code: it expired or never started. Send the phone and consent again. |
account_reconnect_required | 409 | Marked. Your consent was withdrawn, or the provider no longer accepts the sign-in. Nothing was sent. Send the phone and consent again, or the person cancels in the provider's app. |
account_changed | 409 | Marked. Cancel only: the table is on a different account than the one connected now. Nothing was sent: the person cancels in the provider's app. |
not_cancellable_yet | 409 | Marked. Cancel while booking or checking. Nothing was sent. Cancel once it settles. |
terms_unreadable | 409 | Marked. Cancel only, on a booked table: Layout could not read the cancellation fee or deposit. Nothing was sent: the person cancels in the provider's app. On a booking it is a failure.code instead. |
wrong_code | 422 | Marked. Not the code the provider sent. Ask the person again. |
wrong_email | 422 | Marked. The provider did not accept that email. Ask again. |
account_exists | 409 | The person already has that system connected on another number. Nothing was sent. They disconnect it in their Layout account first. |
rate_limited | 429 | Wait Retry-After. Also a second search while one runs. See Limits. |
unavailable | 503 | Layout could not reach the booking system, read the reservation, or record the consent. Nothing was sent. Retry shortly. |
Failure codes
On a failed reservation, as failure.code. Show failure.message.
failure.code | What happened |
|---|---|
expired | It waited past expiresAt. Search again. |
withdrawn | Cancelled while pending. |
slot_unavailable | The time is no longer offered. Search again. |
paid_table_unavailable | The table has a deposit, a cancellation fee or a card hold, and your application does not have paid tables. See Overview. |
terms_unreadable | Layout could not read the deposit or fees, so nothing was offered. |
provider_refused | The provider turned the request down, for example the party size. |
provider_declined | The provider did not take the booking. |
Nothing was booked in any of them.
On an unresolved reservation, Layout could not confirm the outcome. Ask the person to check their provider app, and do not book again blindly.
failure.code | What happened |
|---|---|
unresolved | Layout could not confirm the booking. It may or may not stand. |
cancel_unconfirmed | The booking was confirmed, but Layout could not confirm the cancel. It may still stand. |
Sandbox
Sandbox keys get the same routes against eight test places beside any point. Nothing real is booked or texted, and the consent record and webhooks are written as in production.
| Place | What it does |
|---|---|
| Sandbox Diner | Free. Books at once. |
| Sandbox Steakhouse | A card hold, Visa 4242: no deposit, $25 per guest to cancel within 24 hours of the table. Asks confirm, and cancelling asks one too. |
| Sandbox Email Sign-in | The sign-in asks connect_code, then connect_email, then connect_code with codeFrom: "email". Then free. |
| Sandbox Card Required | add_card first. action: "retry" finds the card and asks confirm; the yes books. |
| Sandbox Terms Change | $10 per guest when read, $20 at the book: the first confirm is 409 terms_changed, the second books. |
| Sandbox Checking | Answers checking. The next GET reads the account and it is booked. |
| Sandbox Unavailable | failed, slot_unavailable. |
| Sandbox Declined | failed, provider_declined. |
- Connect with
provider: "sandbox"or a sandboxplaceId, or inside a booking. Any US or Canadian number works. - Code
000000signs in,000002is409 code_expired, and any other is422 wrong_code. - A connection lasts for that person in your application until you delete it.
- Times are on the date and the night after, only an hour or more ahead. Search with
nearsearches San Francisco, and every place comes back whatever thequery.
CLI
With the Layout CLI. It sends POSTs and DELETEs only with a sandbox key. A POST sends the body's idempotencyKey as the Idempotency-Key header, and code and phone stay strings.
layout api post /v1/users/usr_4b8e9a01c2d3/connections -d provider=sandbox -d phone=+15551234567 -d consent=true layout api post /v1/users/usr_4b8e9a01c2d3/connections/sandbox/respond -d code=000000 layout api get /v1/users/usr_4b8e9a01c2d3/connections layout api post /v1/reservations/search -d near="San Francisco, CA" -d date=2026-11-20 -d time=19:00 -d partySize=2 -d userId=usr_4b8e9a01c2d3 layout api post /v1/reservations -d userId=usr_4b8e9a01c2d3 -d slotId=rs_... --idempotency-key 7f3c2a9e-resv-1 layout api post /v1/reservations/rsv_5d0c2b1e8a4f4c3e9b7a2f1e0d9c8b7a/respond -d userId=usr_4b8e9a01c2d3 -d confirm=cf_b_... layout api post /v1/reservations/rsv_5d0c2b1e8a4f4c3e9b7a2f1e0d9c8b7a/respond -d userId=usr_4b8e9a01c2d3 -d action=retry layout api post /v1/reservations/rsv_5d0c2b1e8a4f4c3e9b7a2f1e0d9c8b7a/cancel layout api get /v1/reservations/rsv_5d0c2b1e8a4f4c3e9b7a2f1e0d9c8b7a layout api get "/v1/reservations?userId=usr_4b8e9a01c2d3" layout api delete /v1/users/usr_4b8e9a01c2d3/connections/sandbox