---
title: "Book an appointment"
method: POST
path: "/api/sites/multiscreen/{site_name}/booking/appointments"
tags: ["Native booking appointments api"]
---

# Book an appointment

`POST /api/sites/multiscreen/{site_name}/booking/appointments`

## Request

- Base URL: `https://api.duda.co`
- URL: `https://api.duda.co/api/sites/multiscreen/{site_name}/booking/appointments`
- Auth: HTTP basic

Creates a booking for the given appointment type and slot. Only free appointment types can be booked through this API; a paid appointment type (see pricing_type on the appointment type) returns 400, since paid appointments can only be booked through the site's cart and checkout UI, which collects payment first. On conflict the API returns 400 (the host already has a booking at this time or is not available); the agent should re-query /availability and pick a different slot.

## Path parameters

- `site_name` string, required

## Request body

- ApiCreateAppointmentRequest
  - `appointment_type_id` string, required: Duda id of the appointment type to book. Required.
  - `attendee` ApiCreateAppointmentAttendee, required: Attendee details. Required.
    - `email` string, required: Attendee email.
    - `language` 'en' | 'fr' | 'it' | 'ru' | 'es' | 'de' | 'pt' | 'ro' | 'nl' | 'pt-BR' | 'es-419' | 'ko' | 'ja' | 'pl' | 'ar' | 'iw-TL' | 'zh-HK' | 'zh-CN' | 'zh-TW' | 'cs' | 'sr' | 'sv' | 'no' | 'fi' | 'da' | 'he' | 'tr' | 'uk' | 'vi' | 'hu' | 'id' | 'ms' | 'th' | 'sk' | 'bg' | 'hr' | 'lt' | 'sl' | 'hi' | 'et' | 'lv' | 'el' | 'ca': Attendee preferred language for confirmation emails.
    - `name` string, required: Attendee full name.
    - `phone_number` string: Attendee phone number in E.164 format. Optional, in addition to the email.
    - `time_zone` string, required: Attendee IANA timezone.
  - `booking_fields_responses` object: Free-form custom-field responses configured on the appointment type.
  - `duration` integer: Override slot duration in minutes. Only for variable-length event types.
  - `guests` string[]: Extra guest emails to CC on confirmation.
  - `metadata` object: Caller-supplied metadata stored with the appointment. Useful for agent attribution. The key `bookingSource` is reserved and rejected.
  - `start` string, required: Slot start time, ISO 8601 UTC. Required.

## Response `200`

OK

- ApiAppointmentResponse
  - `absent_host` boolean: Whether the host is absent
  - `appointment_type` ApiEventType: Appointment type
    - `id` string: Event type ID
    - `slug` string: Event type slug
  - `attendees` ApiSeatedAttendee[]: Appointment attendees
    - `absent` boolean: Whether the attendee is absent
    - `booking_fields_responses` object: Booking fields responses
    - `email` string: Attendee email
    - `language` 'en' | 'fr' | 'it' | 'ru' | 'es' | 'de' | 'pt' | 'ro' | 'nl' | 'pt-BR' | 'es-419' | 'ko' | 'ja' | 'pl' | 'ar' | 'iw-TL' | 'zh-HK' | 'zh-CN' | 'zh-TW' | 'cs' | 'sr' | 'sv' | 'no' | 'fi' | 'da' | 'he' | 'tr' | 'uk' | 'vi' | 'hu' | 'id' | 'ms' | 'th' | 'sk' | 'bg' | 'hr' | 'lt' | 'sl' | 'hi' | 'et' | 'lv' | 'el' | 'ca': Attendee preferred language for confirmation emails.
    - `metadata` object: Metadata
    - `name` string: Attendee name
    - `phone_number` string: Attendee phone number
    - `seat_uid` string: Seat UID
    - `time_zone` string: Attendee timezone
  - `booking_fields_responses` object: Booking fields responses
  - `cancellation_reason` string: Cancellation reason
  - `cancelled_by_email` string: Email of the user who cancelled the appointment
  - `created_at` string, date-time: Creation timestamp
  - `description` string: Appointment description
  - `duration` number: Appointment duration in minutes
  - `end` string: Appointment end time
  - `hosts` ApiBookingHost[]: Appointment hosts
    - `email` string: Host email
    - `id` string: Host ID
    - `name` string: Host name
    - `time_zone` string: Host timezone
    - `username` string: Host username
  - `ics_uid` string: ICS UID
  - `id` integer: Appointment ID
  - `location` string: Appointment location
  - `metadata` object: Metadata stored with the appointment: what the caller supplied, plus the appointment-type, pricing and `bookingSource` fields the product itself writes
  - `rating` number: Appointment rating
  - `recurring_booking_uid` string: Recurring booking UID
  - `rescheduled_by_email` string: Email of the user who rescheduled the appointment
  - `rescheduled_from_uid` string: UID of the previous appointment from which this booking was rescheduled
  - `rescheduling_reason` string: Rescheduling reason
  - `start` string: Appointment start time
  - `status` 'accepted' | 'cancelled' | 'pending' | 'rejected': Appointment status
  - `title` string: Appointment title
  - `uid` string: Appointment UID
  - `updated_at` string, date-time: Last update timestamp

## Other responses

- `400`: Non-OK response from the server
- `401`: Unauthorized request - missing or invalid credentials
- `429`: Rate limit exceeded - please refer to api documentation for limits

---

[API](https://skmtc.dev/duda/apis/duda-partner-api.md) - [All operations](https://skmtc.dev/duda/apis/duda-partner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/duda/apis/duda-partner-api/revisions/52be4d41cb12?raw)