Create appointment booking (Public)

Create a new appointment booking. Can be used by external users without authentication. The contact is resolved by the first identity the request supplies, in this order: contact_id, then contact_phone (alias phone), then contact_name plus contact_email. A phone that is not already in the workspace creates a contact; a phone that matches an existing one books against it and does not overwrite its name.

POST

https://api.channelautomation.com/api/calendar/book

Request body JSON required

workspace_id
string
required
Workspace ID

slot_id
optional
string
The id of a time returned by the availability endpoints. Supplying it replaces date, start_time, end_time and timezone entirely, and it wins if those are sent too. The id is re-resolved against live availability rather than trusted, so an invented time or a slot that filled up since it was offered is rejected with a 400 instead of booked. Ids embed the event type, so they must not be cached beyond the current conversation.
contact_id
optional
string
Existing contact ID (optional if creating new contact)
contact_name
optional
string
Contact name (required for new contacts)
contact_email
optional
string
Contact email (required for new contacts)

format: email
contact_phone
optional
string
Contact phone number (optional)
event_title
optional
string
Title of the appointment
event_description
optional
string
Description of the appointment
date
optional
string
Date in mm-dd-yyyy format (user-friendly)
start_time
optional
string
Start time in hh:mm AM/PM format (user-friendly)
end_time
optional
string
End time in hh:mm AM/PM format (user-friendly)
timezone
optional
string
IANA timezone identifier
location
optional
string
Location of the appointment
notes
optional
string
Additional notes
product_interest
optional
string
Product or service of interest

Example requests

{
  "workspace_id": "workspace-uuid",
  "contact_name": "John Smith",
  "contact_email": "john@example.com",
  "contact_phone": "+1234567890",
  "event_title": "Kitchen Consultation",
  "event_description": "Discuss renovation plans",
  "date": "07-15-2025",
  "start_time": "2:30 PM",
  "end_time": "3:30 PM",
  "timezone": "America/New_York",
  "location": "Customer's home",
  "product_interest": "Kitchen Renovation"
}

{
  "contact_id": "existing-contact-uuid",
  "workspace_id": "workspace-uuid",
  "event_title": "Follow-up Consultation",
  "date": "07-16-2025",
  "start_time": "10:00 AM",
  "end_time": "11:00 AM",
  "timezone": "America/Chicago",
  "location": "Virtual Meeting",
  "product_interest": "Bathroom Renovation"
}

{
  "workspace_id": "61395",
  "contact_phone": "+15551234567",
  "slot_id": "9497f193-774e-489e-9687-8cea9237c41d:2026-09-22T00:00:00.000Z"
}

{
  "workspace_id": "61395",
  "contact_phone": "+15551234567",
  "event_type_id": "36816f8e-8f68-47f4-bdaa-26619bc16b03",
  "start_time": "2026-09-18T16:00:00.000Z",
  "end_time": "2026-09-19T00:00:00.000Z",
  "timezone": "America/Los_Angeles"
}

{
  "workspace_id": "workspace-uuid",
  "contact_name": "Jane Doe",
  "contact_email": "jane@example.com",
  "event_title": "Legacy Format Test",
  "start_time": "2025-07-15T14:00:00Z",
  "end_time": "2025-07-15T15:00:00Z",
  "product_interest": "Testing"
}

Returns

201

Booking created successfully

JSON

success
optional
boolean
booking
optional
object
- id
  optional
  string
  Unique appointment identifier
- contact_id
  optional
  string
  Associated contact ID
- workspace_id
  optional
  string
  Workspace ID
- created_by
  optional
  string
  ID of user who created the appointment
- title
  optional
  string
  Appointment title
- description
  optional
  string
  Appointment description
- appointment_date
  optional
  string
  Date and time of the appointment
  
  format: date-time
- duration_minutes
  optional
  integer
  Duration of the appointment in minutes
- location
  optional
  string
  Location of the appointment
- created_at
  optional
  string
  When the appointment was created
  
  format: date-time
- updated_at
  optional
  string
  When the appointment was last updated
  
  format: date-time
}
appointment
optional
object
- id
  optional
  string
  Unique appointment identifier
- contact_id
  optional
  string
  Associated contact ID
- workspace_id
  optional
  string
  Workspace ID
- created_by
  optional
  string
  ID of user who created the appointment
- title
  optional
  string
  Appointment title
- description
  optional
  string
  Appointment description
- appointment_date
  optional
  string
  Date and time of the appointment
  
  format: date-time
- duration_minutes
  optional
  integer
  Duration of the appointment in minutes
- location
  optional
  string
  Location of the appointment
- created_at
  optional
  string
  When the appointment was created
  
  format: date-time
- updated_at
  optional
  string
  When the appointment was last updated
  
  format: date-time
}
contact_id
optional
string
The contact the booking was attached to, however it was resolved

format: uuid
contact_created
optional
boolean
True when this request created the contact rather than matching one
contact_resolved_via
optional
contact_id
or
phone
or
name_email
or null
Which identity in the request the contact was resolved from
slot_id
optional
string
or null
Echoed back when the booking was made from a slot id, else null
message
optional
string

400

Missing required fields or invalid data

JSON

success
optional
boolean
error
optional
string

409

Time slot conflict

JSON

success
optional
boolean
error
optional
string

500

Internal server error

JSON

error
optional
string
details
optional
string
success
optional
boolean

curl --request POST \ --url https://api.channelautomation.com/api/calendar/book \ --header 'Content-Type: application/json' \ --data @- <<'EOF' { "workspace_id": "workspace-uuid", "contact_name": "John Smith", "contact_email": "john@example.com", "contact_phone": "+1234567890", "event_title": "Kitchen Consultation", "event_description": "Discuss renovation plans", "date": "07-15-2025", "start_time": "2:30 PM", "end_time": "3:30 PM", "timezone": "America/New_York", "location": "Customer's home", "product_interest": "Kitchen Renovation" } EOF

{ "success": true, "booking": { "id": "appointment-uuid", "contact_id": "contact-uuid", "workspace_id": "workspace-uuid", "created_by": "464cf603-5a10-4470-a100-331fc0766680", "title": "Kitchen Renovation - John Smith", "description": "Kitchen Renovation booking for John Smith (john@example.com)", "appointment_date": "2025-07-15T09:00:00Z", "duration_minutes": 60, "location": "Customer's home", "created_at": "2025-07-08T10:00:00Z", "updated_at": "2025-07-08T10:00:00Z" }, "appointment": { "id": "appointment-uuid", "contact_id": "contact-uuid", "workspace_id": "workspace-uuid", "created_by": "464cf603-5a10-4470-a100-331fc0766680", "title": "Kitchen Renovation - John Smith", "description": "Kitchen Renovation booking for John Smith (john@example.com)", "appointment_date": "2025-07-15T09:00:00Z", "duration_minutes": 60, "location": "Customer's home", "created_at": "2025-07-08T10:00:00Z", "updated_at": "2025-07-08T10:00:00Z" }, "contact_id": "f245e2a3-e141-4d41-912c-b1c1f5bd5598", "contact_created": false, "contact_resolved_via": "phone", "slot_id": "9497f193-774e-489e-9687-8cea9237c41d:2026-09-22T00:00:00.000Z", "message": "Booking created successfully" }