Skip to content
Developer docsChannel Automation Developers
First requestVisit website ↗
Navigation

Create an appointment by phone number

Looks up an existing contact by phone number in the workspace, or creates a new one from the provided payload, and inserts an appointment row. Calendar links (Google, Outlook, iCal) are auto-generated by a database trigger immediately after insert. The "Appointment Booked" flow trigger is fired automatically and any active sequences for the contact are stopped.

Required fields: phone_number, adate, atime. Everything else is optional.

Timezone resolution priority (used to convert adate+atime to UTC):

  1. Existing contact's timezone column (if the phone matches a contact that has a timezone set)
  2. Phone area code → IANA timezone (works for all US numbers via the built-in area code map)
  3. Caller-provided adate_utc (used as-is if neither of the above succeeds)
  4. UTC (treat adate+atime as UTC — last resort)

The resolved booking_timezone is stored on the appointment row so the LiveChat UI and calendar view can display times in the correct local zone.

POST
https://api.channelautomation.com/api/appointments

Authorization

  • BearerAuth
    optional
    HTTP Bearer (JWT)
  • ApiKeyAuth
    optional
    API key in header

Request body JSON required

  • phone_number
    string
    required

    Contact phone number. Accepts E.164 or legacy formats (e.g. "17198592496", "+17198592496", "(719) 859-2496"). The service searches multiple variants to avoid creating duplicate contacts.

  • adate
    string
    required

    Local appointment date (YYYY-MM-DD).

  • atime
    string
    required

    Local appointment time (HH:MM, 24-hour).

  • name
    optional
    string

    Full name. Split into firstname/lastname on first space. Only used when creating a NEW contact; ignored if the phone matches an existing contact.

  • street
    optional
    string

    Street address. Stored in contacts.st_address. Only applied when creating a NEW contact.

  • city
    optional
    string
  • state
    optional
    string
  • zipCode
    optional
    string

    ZIP / postal code. Stored in contacts.zip.

  • product
    optional
    string

    Product or service the contact is interested in. Stored in contacts.product. Only applied when creating a NEW contact; ignored if the phone matches an existing contact (the existing product value is preserved). Used by AI appointment setter templates and merge fields like {{contact.product}}.

  • adate_utc
    optional
    string

    Optional. Pre-computed UTC timestamp (ISO 8601). Only used as a fallback when the service cannot resolve a timezone for the contact (i.e. neither an existing contact timezone nor a recognized US phone area code). If omitted, the service will resolve a timezone from the contact or phone number, then compute UTC from adate + atime.

    format: date-time

Returns

201

Appointment created successfully. Existing contact was reused (or a new one was created), and the "Appointment Booked" flow trigger has been dispatched.

JSON
  • success
    optional
    boolean
  • appointment_id
    optional
    string

    UUID of the newly created appointment row.

    format: uuid
  • contact_id
    optional
    string

    UUID of the contact the appointment is linked to (existing or newly created).

    format: uuid
  • is_new_contact
    optional
    boolean

    True if a new contact was created as part of this call. False if an existing contact was reused.

400

Invalid request payload (missing phone number or datetime)
JSON
  • success
    optional
    boolean
  • error
    optional
    string

    Human-readable error message.

  • reason
    optional
    string

    Short error code for programmatic handling. Possible values:

    • missing_phone
    • missing_adate
    • missing_atime
    • missing_workspace
    • missing_workspace_context
    • contact_upsert_failed
    • contact_upsert_exception
    • datetime_resolution_failed
    • appointment_insert_failed
    • appointment_insert_exception
    • unhandled_exception

    Additional values returned by PUT /api/appointments:

    • missing_identifier (neither contact_id nor phone_number provided)
    • invalid_contact_id (contact_id is not a valid UUID)
    • contact_not_found
    • contact_lookup_failed
    • appointment_lookup_failed
    • appointment_update_failed
    • feature_disabled (APPOINTMENT_UPDATE_API flag is off for the workspace)

401

Authentication required
JSON
  • error
    optional
    string
  • success
    optional
    boolean

403

API key does not have contacts.write permission

500

Appointment creation failed (DB error, contact upsert failure, etc.)
JSON
  • success
    optional
    boolean
  • error
    optional
    string

    Human-readable error message.

  • reason
    optional
    string

    Short error code for programmatic handling. Possible values:

    • missing_phone
    • missing_adate
    • missing_atime
    • missing_workspace
    • missing_workspace_context
    • contact_upsert_failed
    • contact_upsert_exception
    • datetime_resolution_failed
    • appointment_insert_failed
    • appointment_insert_exception
    • unhandled_exception

    Additional values returned by PUT /api/appointments:

    • missing_identifier (neither contact_id nor phone_number provided)
    • invalid_contact_id (contact_id is not a valid UUID)
    • contact_not_found
    • contact_lookup_failed
    • appointment_lookup_failed
    • appointment_update_failed
    • feature_disabled (APPOINTMENT_UPDATE_API flag is off for the workspace)

Type to search…

↑↓ navigate↵ selectEsc close