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

  1. Search for places and times: POST /v1/reservations/search.
  2. Book a time: POST /v1/reservations. It books at once when it can.
  3. Respond while next is 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.ask in the thread, and send the person's reply to respond.
  • An app with its own UI. Render each next.kind natively, 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 phone goes with consent: 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 is 422 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 is 422 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 }'
FieldRequiredNotes
providerThis, or placeId, never bothopentable or resy. A sandbox key: sandbox.
placeIdThis, or provider, never bothA place from search. Connects the system it books through.
phoneYesThe number on the person's booking account.
consentYestrue.
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.

ConnectionNotes
providerThe booking system's name, to show.
statepending (waiting on next), connected, or needs_reconnect (send the phone and consent again).
nextnull, 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.

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"
  }'
FieldRequiredNotes
nearThis, or lat and lngA city, neighbourhood or address, up to 120 characters.
lat, lngThese, or nearNumbers, sent together. Used over near when both are sent.
dateYesYYYY-MM-DD. Not past, and at most 90 days out.
timeNoHH:MM, 24-hour, the restaurant's local time. Times nearest it come first.
partySizeYesA whole number, 1 to 50.
queryNoA restaurant name or kind of food, up to 100 characters.
userIdNoThe person. Adds ready to each place.
radiusMilesNo1 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": []
}
FieldNotes
placesUp to 20. Empty when nothing is open.
incomplete, unreadSourcestrue, 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.
idThe place. Opaque.
name, areaShow both, so the person can tell places apart.
address, phoneAs the provider states them, or null.
timeZoneThe place's IANA zone. Every localTime is on this clock.
bookedThroughThe booking system's name, to show. Never branch on it.
readyOnly with userId. true when the person is connected for your application and books without a sign-in. Absent when Layout could not tell.
timesUp to 10, nearest to time first. A place with no time that night gets the next nights' times.
slotIdThe time to book. Send it exactly as given. It also carries the place's name, address and phone, so a new booking shows them.
localTimeYYYY-MM-DDTHH:MM at the place. Show the date: it can be a later night than date.
tableTypeThe 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"
  }'
FieldRequiredNotes
userIdYesThe person, from Provisioning users.
slotIdYesFrom search. A sandbox key books only sandbox places, and a live key only real ones.
Idempotency-Key header, or idempotencyKeyYesUp 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.
referenceNoYour own string, 1 to 200 characters, echoed on the Reservation.
phone, consentNoConnects 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.

FieldNotes
idrsv_ and 32 characters. Opaque.
stateSee below.
versionAn integer that grows when the reservation changes. It never decreases, and two can tie.
createdAtISO 8601, UTC.
expiresAtOnly 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.
referenceYour reference, or null.
placeid, 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, partySizeThe time at the place, and the party.
termsnull until Layout has read the table. See below.
confirmationNumberThe provider's confirmation number once the booking is proven: booked, cancelling, cancelled, and unresolved when the provider gave one. Otherwise null.
nextnull, or the step Layout waits on. See Respond.
failureOnly when failed or unresolved: code and message. See Failure codes.
termsNotes
depositMoney.
cancellationFeeMoney. The whole party's fee.
freeCancelUntilAn ISO 8601 instant, or null.
perGuesttrue 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.

stateMeaningWhat you do
pendingWaiting on next.Respond before expiresAt. With next: null, respond with action: "retry".
bookingLayout is booking.Wait for the webhook, or get it.
bookedConfirmed, and seen on the person's own account.Tell the person.
checkingLayout is reading the person's account to learn whether it booked.Never retry or book again. Wait for the webhook, or get it later.
unresolvedFinal. Layout could not confirm the outcome. See failure.Ask the person to check their provider app. Do not book again blindly.
failedNot booked. See failure.Show failure.message.
cancellingLayout is cancelling.Wait.
cancelledCancelled.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.kindWhat happenedSend
connectThe person is not connected for your application.Ask for the phone on their booking account, then { "userId", "phone", "consent": true }
connect_codeThe provider sent a code. codeFrom is sms or email.{ "userId", "code" }
connect_emailThe provider asks for the account's email.{ "userId", "email" }
confirmA deposit, a cancellation fee or a card hold.Show the terms, then { "userId", "confirm": next.confirmId }
add_cardThe 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" }
  • ask is a sentence Layout writes from the terms. Show or text it as is, or render your own from every terms field, the card included.
  • action: "resend" asks the provider for a new code to the same number. action: "retry" runs the pending step again: after add_card, or after a 503.
  • phone starts a new sign-in, even over one waiting on a code.
  • code is 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 booked with next.kind confirm. Show the terms, then respond with confirm. A later GET shows next: null until you cancel again.
  • Pending: ends failed with withdrawn. 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", ... }
}
CodeStatusWhat it means, and what to do
invalid_request400, 422400: 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_enabled403Your application does not have early access. Contact us.
not_found404No such user, reservation or connection for your application and key.
idempotency_conflict409The key was used for another slot. Send a new key.
wrong_step409Marked. Not what next asks for. Send what it asks.
terms_changed409Marked. The terms changed, or the confirmId is stale. Show the new terms, then confirm with the new confirmId.
code_expired409Marked. No sign-in is waiting for a code: it expired or never started. Send the phone and consent again.
account_reconnect_required409Marked. 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_changed409Marked. 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_yet409Marked. Cancel while booking or checking. Nothing was sent. Cancel once it settles.
terms_unreadable409Marked. 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_code422Marked. Not the code the provider sent. Ask the person again.
wrong_email422Marked. The provider did not accept that email. Ask again.
account_exists409The person already has that system connected on another number. Nothing was sent. They disconnect it in their Layout account first.
rate_limited429Wait Retry-After. Also a second search while one runs. See Limits.
unavailable503Layout 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.codeWhat happened
expiredIt waited past expiresAt. Search again.
withdrawnCancelled while pending.
slot_unavailableThe time is no longer offered. Search again.
paid_table_unavailableThe table has a deposit, a cancellation fee or a card hold, and your application does not have paid tables. See Overview.
terms_unreadableLayout could not read the deposit or fees, so nothing was offered.
provider_refusedThe provider turned the request down, for example the party size.
provider_declinedThe 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.codeWhat happened
unresolvedLayout could not confirm the booking. It may or may not stand.
cancel_unconfirmedThe 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.

PlaceWhat it does
Sandbox DinerFree. Books at once.
Sandbox SteakhouseA 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-inThe sign-in asks connect_code, then connect_email, then connect_code with codeFrom: "email". Then free.
Sandbox Card Requiredadd_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 CheckingAnswers checking. The next GET reads the account and it is booked.
Sandbox Unavailablefailed, slot_unavailable.
Sandbox Declinedfailed, provider_declined.
  • Connect with provider: "sandbox" or a sandbox placeId, or inside a booking. Any US or Canadian number works.
  • Code 000000 signs in, 000002 is 409 code_expired, and any other is 422 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 near searches San Francisco, and every place comes back whatever the query.

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