# Booking Create

## Create a Booking

Use this endpoint to create a new booking.\
**To prevent duplicates, you must provide a unique `booking.id` (UUID v4) generated by your client.**\
**You must also provide either an existing `guest.id` or full guest details inside `guest`.**

#### Endpoint

```http
POST /api/v1/client/bookings
```

#### Example `curl`

```bash
curl "https://api.hostelmate.co/api/v1/client/bookings" \
  -X POST \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-uuid>" \
  -d '{
    "booking": {
      "id": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
      "dates": [
        { "date": "2025-11-05", "amount": 25000 },
        { "date": "2025-11-06", "amount": 25000 },
        { "date": "2025-11-07", "amount": 25000 }
      ]
    },
    "room": "92b6f8b8-6ea2-4e0e-9b7b-3e2f9b6a7c2d",
    "guest": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "phone": "+447712345678",
      "country_code": "GB"
    },
    "notes": "Late arrival around 22:00"
  }'
```

> **`Idempotency-Key` is required** on this endpoint. Omitting it returns `400 bad_request`.

> If `guest.id` is provided, the identity comes from that ID. If `guest.id` is **not** provided, `guest.first_name`, `guest.last_name`, and `guest.email` are required to create a new guest record. The `guest.id` here refers to an existing guest's `guestId` as returned by the [Guests API](/api-documentation/guests/get.md) — it is **not** the `guest.id` embedded in booking responses.

***

#### Request Payload

**Top-level Fields**

<table><thead><tr><th width="104.3515625">Field</th><th width="92.70703125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>booking</code></td><td>object</td><td>Booking info including a client-generated unique ID and nightly amounts.</td></tr><tr><td><code>room</code></td><td>string</td><td>The selected room or room type ID (UUID).</td></tr><tr><td><code>guest</code></td><td>object</td><td>Guest reference <em>or</em> full guest details (see “Guest Object”).</td></tr><tr><td><code>notes</code></td><td>string</td><td>Internal notes for the booking (optional).</td></tr></tbody></table>

**Booking Object**

<table><thead><tr><th width="104.3515625">Field</th><th width="92.70703125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>string</td><td><strong>Required.</strong> Client-generated unique booking ID (UUID v4). Used to prevent duplicate processing.</td></tr><tr><td><code>dates</code></td><td>array</td><td>Array of nightly pricing items. The server computes <em>total</em> from the sum of these amounts.</td></tr></tbody></table>

**Dates Item**

<table><thead><tr><th width="104.3515625">Field</th><th width="92.70703125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>date</code></td><td>string</td><td>Night date (format: YYYY-MM-DD).</td></tr><tr><td><code>amount</code></td><td>integer</td><td>Nightly amount in minor units (e.g., fils/cents).</td></tr></tbody></table>

**Guest Object**

<table><thead><tr><th width="104.3515625">Field</th><th width="92.70703125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>string</td><td>Existing guest ID (UUID). If provided, this identifies the guest.</td></tr><tr><td><code>first_name</code></td><td>string</td><td>Required if <code>id</code> is not provided.</td></tr><tr><td><code>last_name</code></td><td>string</td><td>Required if <code>id</code> is not provided.</td></tr><tr><td><code>email</code></td><td>string</td><td>Required if <code>id</code> is not provided. Must be a valid email.</td></tr><tr><td><code>phone</code></td><td>string</td><td>Optional. E.164 format recommended (e.g., <code>+447...</code>).</td></tr><tr><td><code>country_code</code></td><td>string</td><td>Optional. ISO 3166-1 alpha-2 (e.g., <code>GB</code>).</td></tr><tr><td><code>address</code></td><td>object</td><td>Optional postal address (see below).</td></tr></tbody></table>

**Address Object**

<table><thead><tr><th width="104.3515625">Field</th><th width="92.70703125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>line1</code></td><td>string</td><td>Street line 1.</td></tr><tr><td><code>city</code></td><td>string</td><td>City.</td></tr><tr><td><code>postal_code</code></td><td>string</td><td>Postal/ZIP code.</td></tr><tr><td><code>country_code</code></td><td>string</td><td>ISO 3166-1 alpha-2 (e.g., <code>GB</code>).</td></tr></tbody></table>

***

#### Response (201 Created)

```json
{
  "bookingId": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
  "status": "confirmed",
  "room": "92b6f8b8-6ea2-4e0e-9b7b-3e2f9b6a7c2d",
  "total": 75000,
  "dates": [
    { "date": "2025-11-05", "amount": 25000 },
    { "date": "2025-11-06", "amount": 25000 },
    { "date": "2025-11-07", "amount": 25000 }
  ],
  "guest": {
    "id": "f1b2c3d4-5678-49ab-9cde-112233445566",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com"
  },
  "createdAt": "2025-10-02T09:20:17Z"
}
```

***

#### Validation Rules

* `booking.id` is required and must be a UUID v4. Re-using it with a different payload will be rejected.
* Provide **either** `guest.id` **or** (`guest.first_name`, `guest.last_name`, `guest.email`). Not both.
* `dates[]` must contain at least one item; `date` must be valid (YYYY-MM-DD).
* `amount` must be non-negative integer (minor units).
* The server computes `total` as the sum of `dates[].amount`.

***

#### Error Codes

<table><thead><tr><th width="104.3515625">HTTP</th><th width="92.70703125">Code</th><th>Description</th></tr></thead><tbody><tr><td>400</td><td><code>bad_request</code></td><td>Validation failed (e.g., missing required fields, malformed email, invalid dates).</td></tr><tr><td>404</td><td><code>room_not_found</code></td><td>The specified <code>room</code> does not exist.</td></tr><tr><td>409</td><td><code>booking_id_conflict</code></td><td><code>booking.id</code> already used for a different payload.</td></tr><tr><td>409</td><td><code>availability_conflict</code></td><td>The selected room is no longer available for the requested dates.</td></tr><tr><td>422</td><td><code>guest_invalid</code></td><td><code>guest.id</code> not found or guest fields invalid.</td></tr><tr><td>500</td><td><code>server_error</code></td><td>Unexpected error.</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hostelmate.co/api-documentation/bookings/create.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.