# 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](#search).
2. **Book** a time: [POST /v1/reservations](#book). It books at once when it can.
3. **Respond** while `next` is set: [POST /v1/reservations/:id/respond](#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](https://docs.layout.link/authentication)). Available in early access: [contact us](https://layout.link/contact). 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

```bash
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](#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.

```bash
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`.

```bash
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.

```bash
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](https://docs.layout.link/provisioning). |
| `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](#connect). |

```
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](#respond). |
| `failure` | Only when `failed` or `unresolved`: `code` and `message`. See [Failure codes](#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" }` |

- **`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`.

```bash
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?"
```

```bash
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

```bash
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.

```bash
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](https://docs.layout.link/webhooks). The payload is in [Event types](https://docs.layout.link/events#reservation-updated).

It cannot be fired as a test event. To see one, book a sandbox place.

## Errors

The usual shape (see [Error shape](https://docs.layout.link/errors#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](https://layout.link/contact). |
| `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](https://docs.layout.link/limits#reservations). |
| `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](#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 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](https://docs.layout.link/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
```
