---
title: "Create a booking"
method: POST
path: "/bookings"
tags: ["bookings"]
---

# Create a booking

`POST /bookings`

## Request

- Base URL: `https://agentbookable.com`
- URL: `https://agentbookable.com/bookings`
- Auth: none declared

Creates a real appointment at the provider. Requires a mandate (`mandateRef`) created from the user's instruction. The slot is revalidated at booking time. Check the service's `bookingRequirements` first (e.g. phone required) — missing details return `400` with the missing fields. Include a stable `idempotencyKey` so retries never double-book.

## Request body

- BookingCreate
  - `businessId` string, required
  - `serviceId` string, required
  - `slotId` string: Slot id from the availability call (preferred)
  - `slot` object: Explicit slot when you do not have a slotId
    - `start` string
    - `end` string
    - `staffId` string
  - `customer` object, required
    - `name` string, required
    - `email` string, email
    - `phone` string: Required when the service's bookingRequirements.phone is 'required'
    - `locale` string
    - `timezone` string
  - `mandateRef` string, required: From POST /mandates — single-use, expires in 15 minutes
  - `idempotencyKey` string: Stable key for safe retries
  - `draftId` string: The consented draft (from POST /booking-drafts + POST /mandates/for-draft). Request must match the draft exactly.

## Response `200`

Confirmed booking

- Booking
  - `id` string
  - `businessId` string
  - `serviceId` string
  - `staffId` string, nullable
  - `start` string
  - `end` string
  - `status` 'confirmed' | 'pending' | 'cancelled' | 'completed'
  - `customer` object: Personal data partially masked
    - `name` string
    - `email` string, nullable
    - `phone` string, nullable
  - `createdVia` 'agent'
  - `mandateRef` string
  - `createdAt` string
  - `updatedAt` string

## Other responses

- `400`: Invalid request or missing customer information (see requiredFields)
- `409`: Slot taken — alternatives provided
- `429`: Too many requests — slow down

---

[API](https://skmtc.dev/agentbookable/apis/agentbookable-booking-api-for-ai-agents.md) · [All operations](https://skmtc.dev/agentbookable/apis/agentbookable-booking-api-for-ai-agents/llms.txt) · [OpenAPI document](https://skmtc.dev/agentbookable/apis/agentbookable-booking-api-for-ai-agents/revisions/736963f5951a?raw)