---
title: "Create a booking (charges credits + sends notifications)"
method: POST
path: "/appointments/bookings"
tags: ["Appointments"]
---

# Create a booking (charges credits + sends notifications)

`POST /appointments/bookings`

## Request

- Base URL: `https://be.graph8.com/api/v1`
- URL: `https://be.graph8.com/api/v1/appointments/bookings`
- Auth: HTTP bearer

Create (book) an appointment on behalf of the API key's user.

Reuses ``BookingsHandler.handle_create`` verbatim — same host selection,
conflict checks, credit charge (~20 credits), calendar push, attendee
notifications, and EDA emit as an in-app booking. Surfaces the handler's
402 (insufficient credits) / 409 (slot conflict) / 404 (event type)
untouched.

## Headers

- `Authorization` string, nullable
- `X-Target-Org-Id` string, nullable

## Request body

- CreateBookingRequest
  - `event_type_id` integer, required
  - `start_time` string, required
  - `end_time` string, nullable
  - `override_availability` boolean
  - `attendees` AttendeeInput[], required
    - `name` string, required
    - `email` string, required
    - `time_zone` string, nullable
    - `phone_number` string, nullable
  - `location` string, nullable
  - `selected_location` LocationItem: A single location option on an event type.
    - `kind` 'in_person_host' | 'in_person_attendee' | 'phone_host' | 'phone_attendee' | 'link' | 'conferencing' | 'custom', required: Rich location types for event types.
    - `address` string, nullable
    - `link` string, nullable
    - `phone` string, nullable
    - `provider` string, nullable
    - `display_label` string, nullable
    - `public` boolean
  - `selected_conferencing` LocationItem: A single location option on an event type.
    - `kind` 'in_person_host' | 'in_person_attendee' | 'phone_host' | 'phone_attendee' | 'link' | 'conferencing' | 'custom', required: Rich location types for event types.
    - `address` string, nullable
    - `link` string, nullable
    - `phone` string, nullable
    - `provider` string, nullable
    - `display_label` string, nullable
    - `public` boolean
  - `responses` object, nullable
  - `guests` string[], nullable
  - `metadata` object, nullable
  - `recurring_event_id` string, nullable
  - `language` string
  - `slot_uid` string, nullable

## Response `201`

Successful Response

- object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/graph8/apis/graph8-developer-api.md) · [All operations](https://skmtc.dev/graph8/apis/graph8-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/graph8/apis/graph8-developer-api/revisions/89fc11143b70?raw)