# Get booking!

ℹ️ **The Booking Engine** is the core feature, allowing customers to make reservations, choose rooms, slot times, number of persons and cancel existing bookings.\
\
⚙️ **Use the base resource URL** for the following examples, or [see the complete collection](https://documenter.getpostman.com/view/36615570/2sAY4vhNsy#c65e4fea-6150-4a06-b59b-1701150db978)

```
https://api.octorate.com/octotable-pms/api/v2
```

## 🔍 Find all reservations

<mark style="color:green;">**`GET`**</mark> `/reservations`

Retrieves a list of all reservations for the specified property (e.g., restaurant) using the property ID [see more](https://documenter.getpostman.com/view/36615570/2sAY4vhNsy#31563a21-ed14-4e57-b762-bb2f7e100586)

**Headers**

<table><thead><tr><th width="345">Name</th><th>Value</th></tr></thead><tbody><tr><td><code>Content-Type</code></td><td><code>application/json</code></td></tr><tr><td><code>Authorization</code></td><td><code>Bearer &#x3C;token></code></td></tr><tr><td><code>Property</code></td><td><code>&#x3C;your_property_id></code></td></tr></tbody></table>

**Query params**

<table><thead><tr><th width="345">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>next_cursor</code></td><td>string</td><td>Pagination cursor</td></tr><tr><td><code>limit</code></td><td>int</td><td>Elements limit per page</td></tr><tr><td><code>start_date</code></td><td>date [YYYY-MM-DD]</td><td>Start day of search</td></tr><tr><td><pre><code>start_hour
</code></pre></td><td>[HH:MM:SS]</td><td>Starting hour of the reservation</td></tr><tr><td><code>end_date</code></td><td>date [YYYY-MM-DD]</td><td>End day of search</td></tr><tr><td><code>status[]</code></td><td>[WAITING, ACCEPTED, CANCELLED, CONFIRMED, EXPIRED, PREPAY, OUTOFORDER, REJECTED]</td><td>The status of reservation</td></tr><tr><td><code>text_search</code></td><td>string</td><td>The text search by customer name, last name or phone number</td></tr><tr><td><code>service_ids[]</code></td><td>[int]</td><td>The id list of services</td></tr><tr><td><code>room_ids[]</code></td><td>[int]</td><td>The id list of rooms</td></tr><tr><td>incoming</td><td>Boolean</td><td>Search criteria to retrieve incoming reservations</td></tr><tr><td>arrived</td><td>Boolean</td><td>Search criteria to retrieve arrived reservations</td></tr><tr><td>departed</td><td>Boolean</td><td>Search criteria to retrieve departed reservations</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200 OK" %}

```json
{
  "data": [
    {
      "id": 32992280,
      "pax": 2,
      "status": "CANCELLED",
      "customer": {
        "id": 33942074,
        "first_name": "Adam",
        "last_name": "Devis",
        "email": "adam.devis@email.com",
        "phone": "3332211456"
      },
      "service": {
        "id": 33841,
        "name": "Custom dinner"
      },
      "channel": "OCTOTABLE_ADMIN",
      "room": {
        "id": 23288,
        "name": "Sala Nuova"
      },
      "end_date": "2025-05-15T14:00:00",
      "last_status_change": "2025-05-14T17:06:46",
      "notes": "",
      "special_request": "",
      "start_date": "2025-05-15",
      "start_hour": "13:00:00",
      "tables": [
        {
          "id": 197934,
          "name": "T8",
          "bookable": true,
          "free": true,
          "group": false,
          "online": true,
          "room_id": 23288
        }
      ],
      "waiting_list": false
    },
    {
      "id": 32992285,
      "pax": 2,
      "status": "CANCELLED",
      "customer": {
        "id": 33942079,
        "first_name": "Adam 2",
        "last_name": "Devis 2",
        "email": "adam.devis@email.com",
        "phone": "3332211456"
      },
      "service": {
        "id": 33841,
        "name": "Custom dinner"
      },
      "channel": "OCTOTABLE_ADMIN",
      "room": {
        "id": 23288,
        "name": "Sala Nuova"
      },
      "end_date": "2025-05-15T14:00:00",
      "last_status_change": "2025-05-14T17:09:40",
      "notes": "",
      "special_request": "",
      "start_date": "2025-05-15",
      "start_hour": "13:00:00",
      "tables": [
        {
          "id": 197934,
          "name": "T8",
          "bookable": true,
          "free": true,
          "group": false,
          "online": true,
          "room_id": 23288
        }
      ],
      "waiting_list": false
    },
    {
      "id": 32992293,
      "pax": 2,
      "status": "CANCELLED",
      "customer": {
        "id": 33942086,
        "first_name": "Adam 2",
        "last_name": "Devis 2",
        "email": "adam.devis@email.com",
        "phone": "3332211456"
      },
      "service": {
        "id": 33841,
        "name": "Custom dinner"
      },
      "channel": "OCTOTABLE_ADMIN",
      "room": {
        "id": 23288,
        "name": "Sala Nuova"
      },
      "end_date": "2025-05-15T14:00:00",
      "last_status_change": "2025-05-14T17:09:44",
      "start_date": "2025-05-15",
      "start_hour": "13:00:00",
      "tables": [
        {
          "id": 197934,
          "name": "T8",
          "bookable": true,
          "free": true,
          "group": false,
          "online": true,
          "room_id": 23288
        }
      ],
      "waiting_list": false
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## 🔍 Find reservation by ID

<mark style="color:green;">**`GET`**</mark> `/reservations/{reservation_id}`

Retrieves a reservations by its ID [see more](https://documenter.getpostman.com/view/36615570/2sAY4vhNsy#64635d58-695a-4ec3-9f5d-1996b708c7d4)

**Headers**

| Name            | Value                |
| --------------- | -------------------- |
| `Content-Type`  | `application/json`   |
| `Authorization` | `Bearer <token>`     |
| `Property`      | `<your_property_id>` |

**Response**

{% tabs %}
{% tab title="200 OK" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "data": [
        {
            "id": 31753958,
            "pax": 2,
            "status": "CONFIRMED",
            "customer": {
                "id": 33499559,
                "first_name": "Adam",
                "last_name": "Devis",
                "email": "adam.devis@email.com",
                "phone": "3332211456"
            },
            "service": {
                "id": 30911,
                "name": "Lunch"
            },
            "channel": "OCTOTABLE_ADMIN",
            "room": {
                "id": 21344,
                "name": "Secondary dining room"
            },
            "end_date": "2024-12-14T14:30:00",
            "start_day": "2024-12-14",
            "start_hour": "13:30:00",
            "tables": [
                {
                    "id": 172246,
                    "name": "T8",
                    "bookable": true,
                    "free": true,
                    "group": false,
                    "room_id": 21344
                }
            ],
            "waiting_list": false
        }
    ]
}
</code></pre>

{% endtab %}
{% endtabs %}

## 🆕 Create a new reservation

<mark style="color:yellow;">**`POST`**</mark> `/reservations`

Creates a new reservation for the specified property using the provided reservation details [see more](https://documenter.getpostman.com/view/36615570/2sAY4vhNsy#66fc6de2-19c9-486d-804e-994ddf13fa6a)

**Headers**

| Name            | Value                |
| --------------- | -------------------- |
| `Content-Type`  | `application/json`   |
| `Authorization` | `Bearer <token>`     |
| `Property`      | `<your_property_id>` |

**Body**

<table><thead><tr><th width="256">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>start_date</code></td><td>date [YYYY-MM-DD]</td><td>The start date</td></tr><tr><td><code>start_hour</code></td><td>time [HH:mm:ss]</td><td>The start hour</td></tr><tr><td><code>pax</code></td><td>int</td><td>The number of person</td></tr><tr><td><code>channel</code></td><td>enum [OCTOTABLE_BOOK, OCTOTABLE_ADMIN]</td><td><strong>OCTOTABLE_BOOK</strong>: This indicates reservations made through the <strong>Booking Engine.</strong><br>resents reservations made through <strong>Reserve with Google.</strong><br><strong>OCTOTABLE_ADMIN</strong>: Refers to <strong>self reservations.</strong></td></tr><tr><td><code>customer</code></td><td>Customer </td><td>The customer who makes the reservation</td></tr><tr><td><code>customer.first_name</code></td><td>string</td><td>The customers first name</td></tr><tr><td><code>customer.last_name</code></td><td>string</td><td>The customer last name</td></tr><tr><td><code>customer.email</code></td><td>string</td><td>The customers email</td></tr><tr><td><code>customer.phone</code></td><td>string</td><td>The customers phone</td></tr><tr><td><code>service_id</code></td><td>int</td><td>The id of the selected service</td></tr><tr><td><code>room_id</code></td><td>int</td><td>The id of the selected room</td></tr><tr><td><code>table_ids</code></td><td>[int]</td><td>The list of ids of the selected tables</td></tr><tr><td><code>waiting_list</code></td><td>boolean</td><td>Keep reservation in waiting list</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="201 Created" %}

```json
{
  "data": [
    {
      "id": 31753956,
      "pax": 2,
      "status": "WAITING",
      "customer": {
        "id": 33499557,
        "first_name": "Adam",
        "last_name": "Devis",
        "email": "adam.devis@email.com",
        "phone": "3332211456"
      },
      "service": {
        "id": 30907,
        "name": "Pranzo nuovo"
      },
      "channel": "OCTOTABLE_ADMIN",
      "room": {
        "id": 21343,
        "name": "main dining room"
      },
      "end_date": "2024-12-12T13:30:00",
      "start_date": "2024-12-12",
      "start_hour": "12:30:00",
      "tables": [
        {
          "id": 172245,
          "name": "T8",
          "bookable": true,
          "free": true,
          "group": false,
          "room_id": 21343
        }
      ],
      "waiting_list": false
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## 🟢 Enable Google Engine

<mark style="color:yellow;">**`POST`**</mark> `/reservations/google`

Activates the Google Engine for a specified property [see more](https://documenter.getpostman.com/view/36615570/2sAY4vhNsy#0b0beaba-0891-43b4-bcf3-c1578807d39a)

**Headers**

| Name            | Value                |
| --------------- | -------------------- |
| `Content-Type`  | `application/json`   |
| `Authorization` | `Bearer <token>`     |
| `Property`      | `<your_property_id>` |

**Body**

| Name                   | Type    | Description              |
| ---------------------- | ------- | ------------------------ |
| `enable_google_engine` | boolean | Enable the google engine |

**Response**

{% tabs %}
{% tab title="200 OK" %}

```json
{
  "status": "ACCEPTED"
}
```

{% endtab %}
{% endtabs %}

## 🔄 Update a reservation

<mark style="color:blue;">**`PUT`**</mark> `/reservations/{reservation_id}`

Update an existing reservation [see more](https://documenter.getpostman.com/view/36615570/2sAY4vhNsy#8baf6597-ed12-4402-9e0f-dfbfd9c841ed)

**Headers**

| Name            | Value                |
| --------------- | -------------------- |
| `Content-Type`  | `application/json`   |
| `Authorization` | `Bearer <token>`     |
| `Property`      | `<your_property_id>` |

**Body**

<table><thead><tr><th width="256">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>start_day</code></td><td>date [YYYY-MM-DD ]</td><td>The start day</td></tr><tr><td><code>start_hour</code></td><td>time [HH:mm:ss]</td><td>The start hour</td></tr><tr><td><code>pax</code></td><td>int</td><td>The number of person</td></tr><tr><td><code>service_id</code></td><td>int</td><td>The id of the selected service</td></tr><tr><td><code>room_id</code></td><td>int</td><td>The id of the selected room</td></tr><tr><td><code>table_ids</code></td><td>[int]</td><td>The list of ids of the selected tables</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "data": [
        {
            "id": 31753936,
            "pax": 2,
            "status": "CONFIRMED",
            "customer": {
                "id": 3255826,
                "first_name": "John",
                "last_name": "Smith",
                "email": "john.smith@demo.com",
                "phone": "55555555555"
            },
            "service": {
                "id": 17884,
                "name": "Breakfast"
            },
            "channel": "OCTOTABLE_ADMIN",
            "start_day": "2024-10-30",
            "start_hour": "18:00:00"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## 🔄  Check in

<mark style="color:purple;">**`PATCH`**</mark> `/reservations/{reservation_id}/checkin`

Customers check-in [see more](https://documenter.getpostman.com/view/36615570/2sAY4vhNsy#9c302757-7bb5-4ae8-b070-6f3b70909bd5)

**Headers**

| Name            | Value                |
| --------------- | -------------------- |
| `Content-Type`  | `application/json`   |
| `Authorization` | `Bearer <token>`     |
| `Property`      | `<your_property_id>` |

**Query params**

| Name   | Type    | Description                                  |
| ------ | ------- | -------------------------------------------- |
| `undo` | boolean | Undo check in if it has been made by mistake |

**Response**

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "data": [
        {
            "id": 31753956,
            "pax": 2,
            "status": "ACCEPTED",
            "customer": {
                "id": 33499557,
                "first_name": "Adam",
                "last_name": "Devis",
                "email": "adam.devis@email.com",
                "phone": "3332211456"
            },
            "service": {
                "id": 30907,
                "name": "Pranzo nuovo"
            },
            "channel": "OCTOTABLE_ADMIN",
            "room": {
                "id": 21343,
                "name": "main dining room"
            },
            "checkin_date": "2024-12-12T17:04:04.564",
            "end_date": "2024-12-12T13:30:00",
            "expiration_date": "2024-12-12T17:13:49",
            "start_day": "2024-12-12",
            "start_hour": "12:30:00",
            "tables": [
                {
                    "id": 172245,
                    "name": "T8",
                    "bookable": true,
                    "free": true,
                    "group": false,
                    "room_id": 21343
                }
            ],
            "waiting_list": false
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## 🔄 Check out

<mark style="color:purple;">**`PATCH`**</mark> `/reservations/{reservation_id}/checkout`

Customers check out [see more](https://documenter.getpostman.com/view/36615570/2sAY4vhNsy#f6110d22-a4c2-4dca-bbda-da8c9335e5fb)

**Headers**

| Name            | Value                |
| --------------- | -------------------- |
| `Content-Type`  | `application/json`   |
| `Authorization` | `Bearer <token>`     |
| `Property`      | `<your_property_id>` |

**Query param**

| Name   | Type    | Description                                   |
| ------ | ------- | --------------------------------------------- |
| `undo` | boolean | Undo check out if it has been made by mistake |

**Response**

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "data": [
        {
            "id": 31753958,
            "pax": 2,
            "status": "CONFIRMED",
            "customer": {
                "id": 33499559,
                "first_name": "Adam",
                "last_name": "Devis",
                "email": "adam.devis@email.com",
                "phone": "3332211456"
            },
            "service": {
                "id": 30911,
                "name": "Lunch"
            },
            "channel": "OCTOTABLE_ADMIN",
            "room": {
                "id": 21344,
                "name": "Secondary dining room"
            },
            "end_date": "2024-12-14T14:30:00",
            "start_day": "2024-12-14",
            "start_hour": "13:30:00",
            "tables": [
                {
                    "id": 172246,
                    "name": "T8",
                    "bookable": true,
                    "free": true,
                    "group": false,
                    "room_id": 21344
                }
            ],
            "waiting_list": false
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## 🔄 Update status

<mark style="color:purple;">**`PATCH`**</mark> `/reservations/{reservation_id}`

Update the status of the reservation in waiting list. If on the waiting list, the reservation should become accepted, declined, or confirmed [see more](https://documenter.getpostman.com/view/36615570/2sAY4vhNsy#896d82b8-1120-483e-89ee-642a66af89a3)

**Headers**

| Name            | Value                |
| --------------- | -------------------- |
| `Content-Type`  | `application/json`   |
| `Authorization` | `Bearer <token>`     |
| `Property`      | `<your_property_id>` |

**Query param**

| Name     | Type | Description                                   |
| -------- | ---- | --------------------------------------------- |
| `status` | enum | The status of the reservation in waiting list |

**Response**

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "data": [
        {
            "id": 31753956,
            "pax": 2,
            "status": "WAITING",
            "customer": {
                "id": 33499557,
                "first_name": "Adam",
                "last_name": "Devis",
                "email": "adam.devis@email.com",
                "phone": "3332211456"
            },
            "service": {
                "id": 30907,
                "name": "Pranzo nuovo"
            },
            "channel": "OCTOTABLE_ADMIN",
            "room": {
                "id": 21343,
                "name": "main dining room"
            },
            "end_date": "2024-12-12T13:30:00",
            "start_day": "2024-12-12",
            "start_hour": "12:30:00",
            "tables": [
                {
                    "id": 172245,
                    "name": "T8",
                    "bookable": true,
                    "free": true,
                    "group": false,
                    "room_id": 21343
                }
            ],
            "waiting_list": false
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## 🗑️ Delete a reservation

<mark style="color:red;">**`DELETE`**</mark> `/reservations/{reservation_id}`

Delete a reservation [see more](https://documenter.getpostman.com/view/36615570/2sAY4vhNsy#c5d8e6c9-d242-4ca9-8539-81a6de2a1010)

**Headers**

| Name            | Value                |
| --------------- | -------------------- |
| `Content-Type`  | `application/json`   |
| `Authorization` | `Bearer <token>`     |
| `Property`      | `<your_property_id>` |

**Response**

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "data": [
        172221
    ]
}
```

{% endtab %}
{% endtabs %}

**📕 ADDITIONAL NOTES**&#x20;

**Tables**&#x20;

* <mark style="color:red;">**Bookable / Online**</mark>:\
  These parameters indicate whether a table can be booked online (via the booking engine or Reserve with Google) or only through manual methods such as phone or walk-in (offline).
* <mark style="color:red;">**Free**</mark>:\
  A table is considered *free* if it has no active reservation during the selected time slot. This status is based on the `average_stay` setting.\
  For example, if the average stay is 60 minutes and a reservation starts at 1:00 p.m., the table is marked as occupied from 1:00 p.m. to 2:00 p.m. However, it will also be considered unavailable starting from 12:00 p.m., in order to respect the buffer time before the next reservation.
* <mark style="color:red;">**Group**</mark>:\
  Indicates whether the table is a grouped table (i.e. a combination of two or more individual tables).
  * **Group = true** → The table is formed by merging smaller tables (e.g., *Indoor 1* {2 pax} + *Indoor 2* {2 pax} = *Indoor 1+2* {4 pax}).
  * **Group = false** → It is a standalone table.
* <mark style="color:red;">**Best\_Choice**</mark>:\
  This parameter helps the system determine the most suitable table for a given party size. The goal is to optimize table usage by selecting the table that best fits the number of guests (e.g., assigning a 2-pax table to a 2-person reservation instead of a 4-pax table).