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
Body
| Field | Type | Required | Description |
|---|---|---|---|
organization_id | integer | Yes | Your organization ID (the API key's organization). |
service_id | integer | Yes | Reservation service to book. Must be active. |
contact_id | integer | Yes | Contact the booking is for. |
start_datetime | string (date-time) | Yes | Start, as service wall-clock time (see date and time format). |
end_datetime | string (date-time) | No | Computed from the service duration_minutes when omitted. |
party_size | integer | No | Default 1. Must be between the service min_party_size and max_party_size. |
duration_minutes | integer | No | For services with duration_mode: "flexible": one of the service duration_options. Sets end_datetime and the price. |
payment_choice | string | No | pay_now or pay_later. For services with payment_mode: "optional": pay_now holds the slot until the customer pays online. |
collect_payment | boolean | No | Only for source: "manual": hold the booking as awaiting_payment and create a payment link, like customer bookings. Not stored. |
status | string | No | pending, 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). |
source | string | No | manual, whatsapp_ai, instagram_ai, webchat, public_link, api or automation. Default manual. |
preferred_resource_id | integer | No | Book on this resource. |
customer_notes, internal_notes | string | No | Notes. |
conversation_id, deal_id, company_id, estimate_id, invoice_id | integer | No | Related records. |
google_meet_link | string | No | Video-call link to include in emails. |
payment_status | string | No | none, pending, paid or refunded. Stored as not_required when omitted; set by the server for services with online payments. |
payment_amount | number | No | Amount, minimum 0. |
custom_fields_by_key | object | No | Reservation 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 leastmin_advance_hoursaway. - When
max_advance_days> 0: the date is at mostmax_advance_daysahead. - When
max_daily_bookingsis set: fewer than that manypending/confirmedreservations exist for the service that day. - When
capacity_modeisper_slot: fewer thanslot_capacitypending/confirmedreservations overlap the time (only those onpreferred_resource_idwhen it is sent). - For each linked resource: the resource has a weekly availability block covering the time on that weekday, no
blockedexception that day, and enough freecapacity.requiredresources must pass;optionalones are skipped when busy;any_availablepicks any active resource of the sameresource_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 forcancelledorno_show. - Runs the organization's New reservation automations.
Errors
| Status | When |
|---|---|
400 Bad Request | Missing 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 Forbidden | organization_id is not the API key's organization. |
Report an issue with this documentation
Please log in to report issues with our documentation.