Create a reservation

Books a contact into a service. Pick a slot from available slots and send its start_datetime; the end time is computed from the service duration.

Endpoint

POST
/reservations

Body

FieldTypeRequiredDescription
organization_idintegerYesYour organization ID (the API key's organization).
service_idintegerYesReservation service to book. Must be active.
contact_idintegerYesContact the booking is for.
start_datetimestring (date-time)YesStart, as service wall-clock time (see date and time format).
end_datetimestring (date-time)NoComputed from the service duration_minutes when omitted.
party_sizeintegerNoDefault 1. Must be between the service min_party_size and max_party_size.
duration_minutesintegerNoFor services with duration_mode: "flexible": one of the service duration_options. Sets end_datetime and the price.
payment_choicestringNopay_now or pay_later. For services with payment_mode: "optional": pay_now holds the slot until the customer pays online.
collect_paymentbooleanNoOnly for source: "manual": hold the booking as awaiting_payment and create a payment link, like customer bookings. Not stored.
statusstringNopending, confirmed, cancelled, completed or no_show. Ignored (set to confirmed) when the service has auto_confirm: true, and replaced by awaiting_payment when the booking must be paid online first (see payments).
sourcestringNomanual, whatsapp_ai, instagram_ai, webchat, public_link, api or automation. Default manual.
preferred_resource_idintegerNoBook on this resource.
customer_notes, internal_notesstringNoNotes.
conversation_id, deal_id, company_id, estimate_id, invoice_idintegerNoRelated records.
google_meet_linkstringNoVideo-call link to include in emails.
payment_statusstringNonone, pending, paid or refunded. Stored as not_required when omitted; set by the server for services with online payments.
payment_amountnumberNoAmount, minimum 0.
custom_fields_by_keyobjectNoReservation custom field values keyed by field key.

See the reservation object for every field.

Request

Response

Returns the created reservation object with end_datetime, status, service, contact and assigned_resources. For services with online payments the create response also has pay_url (payment link to send to the customer, or null), payment_required and payment_unavailable_reason (null, or why the payment could not be requested online: no_active_gateway, gateway_inactive, currency_not_supported, no_currency, no_contact, link_failed, error). These three are only in the create response.

json

Validation

Before saving, the API checks, in the service's timezone:

  • The service is active and party_size ≤ max_party_size.
  • When min_advance_hours > 0: the date is not in the past and, for today, the start is at least min_advance_hours away.
  • When max_advance_days > 0: the date is at most max_advance_days ahead.
  • When max_daily_bookings is set: fewer than that many pending/confirmed reservations exist for the service that day.
  • When capacity_mode is per_slot: fewer than slot_capacity pending/confirmed reservations overlap the time (only those on preferred_resource_id when it is sent).
  • For each linked resource: the resource has a weekly availability block covering the time on that weekday, no blocked exception that day, and enough free capacity. required resources must pass; optional ones are skipped when busy; any_available picks any active resource of the same resource_type.

Resources that pass are assigned to the reservation and returned in assigned_resources.

Side effects

  • Sends the confirmation email to the contact (sets confirmation_sent_at) and a notification to staff resources linked to a user, when enabled in the organization's reservation settings (both on by default). Not sent for cancelled or no_show.
  • Runs the organization's New reservation automations.

Errors

StatusWhen
400 Bad RequestMissing required field, invalid enum, inactive service, party size too large, outside the advance-booking window, daily limit reached, slot fully booked, a required resource unavailable, or unknown custom field key. The message says which.
403 Forbiddenorganization_id is not the API key's organization.

Report an issue with this documentation

Please log in to report issues with our documentation.