DUduda
Native booking appointments api

Book an appointment

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.

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

Path parameters

site_namestring required

The site's unique name (its ID), returned when the site is created.

Request body

appointment_type_idstring required

Duda id of the appointment type to book. Required.

booking_fields_responsesobject

Free-form custom-field responses configured on the appointment type.

durationinteger

Override slot duration in minutes. Only for variable-length event types.

guestsstring[]

Extra guest emails to CC on confirmation.

metadataobject

Caller-supplied metadata stored with the appointment. Useful for agent attribution. The key bookingSource is reserved and rejected.

startstring required

Slot start time, ISO 8601 UTC. Required.

Example request

{
  "appointment_type_id": "01JZ83QB5MQFRMXWAVQ55C648W",
  "attendee": {
    "email": "jane@example.com",
    "name": "Jane Doe",
    "phone_number": "+12025550123",
    "time_zone": "America/New_York"
  },
  "booking_fields_responses": {
    "notes": "first visit"
  },
  "duration": 30,
  "guests": [
    "bob@example.com"
  ],
  "metadata": {
    "agent_id": "a-123",
    "source": "ai-chatbot"
  },
  "start": "2026-06-02T14:00:00.000Z"
}

Response

OK

absent_hostboolean

Whether the host is absent

booking_fields_responsesobject

Booking fields responses

cancellation_reasonstring

Cancellation reason

cancelled_by_emailstring

Email of the user who cancelled the appointment

created_atstring date-time

Creation timestamp

descriptionstring

Appointment description

durationnumber

Appointment duration in minutes

endstring

Appointment end time

ics_uidstring

ICS UID

idinteger

Appointment ID

locationstring

Appointment location

metadataobject

Metadata stored with the appointment: what the caller supplied, plus the appointment-type, pricing and bookingSource fields the product itself writes

ratingnumber

Appointment rating

recurring_booking_uidstring

Recurring booking UID

rescheduled_by_emailstring

Email of the user who rescheduled the appointment

rescheduled_from_uidstring

UID of the previous appointment from which this booking was rescheduled

rescheduling_reasonstring

Rescheduling reason

startstring

Appointment start time

status'accepted' | 'cancelled' | 'pending' | 'rejected'

Appointment status

titlestring

Appointment title

uidstring

Appointment UID

updated_atstring date-time

Last update timestamp

Example response

{
  "appointment_type": {
    "id": "2660601",
    "slug": "sample-event"
  },
  "attendees": [
    {
      "absent": false,
      "email": "user@multiscreensite.com",
      "language": "en",
      "name": "Default",
      "timeZone": "Asia/Jerusalem"
    }
  ],
  "booking_fields_responses": {
    "email": "user@multiscreensite.com",
    "guests": [],
    "name": "Default"
  },
  "cancellation_reason": "Schedule conflict",
  "cancelled_by_email": "user@multiscreensite.com",
  "created_at": "2025-06-16T14:31:58.794Z",
  "duration": 30,
  "end": "2025-06-16T18:00:00.000Z",
  "hosts": [
    {
      "email": "staffmember1@multiscreensite.com",
      "id": "1582498",
      "name": "Staff Member 1",
      "time_zone": "Asia/Jerusalem",
      "username": "staffmember1-example-com"
    }
  ],
  "ics_uid": "kko1gv8tFZe8JjpCpct5tG@duda.co",
  "id": 8589828,
  "location": "https://app.example.com/video/kko1gv8tFZe8JjpCpct5tG",
  "metadata": {
    "pricingType": "FREE",
    "source": "qa-test"
  },
  "rating": 5,
  "recurring_booking_uid": "rec_kko1gv8tFZe8JjpCpct5tG",
  "rescheduled_by_email": "user@multiscreensite.com",
  "rescheduled_from_uid": "abc123defGHIjkl456MNO",
  "rescheduling_reason": "Availability changed",
  "start": "2025-06-16T17:30:00.000Z",
  "status": "accepted",
  "title": "Sample Event between Staff Member 1 and Default",
  "uid": "kko1gv8tFZe8JjpCpct5tG",
  "updated_at": "2025-06-16T14:31:59.219Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.