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

Update (reschedule) a contact's appointment

Finds the contact by contact_id or phone_number, then updates their appointment to the new date/time. Both the appointments table row (source of truth — calendar links regenerate automatically) and the contact's appointment_date, appointment_time, and appointment_date_display columns are updated together, so the contact record always matches the appointment.

Which appointment is updated: the contact's next upcoming appointment; if none is upcoming, their most recent one. If the contact has no appointments at all, a new one is created (created_new_appointment: true in the response).

Unlike POST, this endpoint does NOT fire "Appointment Booked" flow triggers or stop sequences — safe to call from a flow's Run API Request action without causing trigger loops. It also never creates a contact: an unknown identifier returns 404.

Required fields: adate, atime, and one of contact_id / phone_number.

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

  1. Caller-provided timezone (IANA name or abbreviation like "PST")
  2. Contact's timezone column
  3. Phone area code → IANA timezone (US numbers)
  4. Caller-provided adate_utc (used as-is)
  5. UTC (last resort)
PUT
https://api.channelautomation.com/api/appointments

Authorization

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

Request body JSON required

  • adate
    string
    required

    New local appointment date (YYYY-MM-DD).

  • atime
    string
    required

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

  • contact_id
    optional
    string

    Contact UUID. Either this or phone_number is required. When both are provided, contact_id wins.

    format: uuid
  • phone_number
    optional
    string

    Contact phone number. Accepts E.164 or legacy formats — the same multi-variant lookup as POST. Used only if contact_id is not provided.

  • timezone
    optional
    string

    Optional IANA timezone (or abbreviation like "PST") to interpret adate+atime in. Overrides the contact's stored timezone.

  • adate_utc
    optional
    string

    Optional pre-computed UTC timestamp, used only as a fallback when no timezone can be resolved.

    format: date-time

Returns

200

Appointment updated (or created when the contact had none).

JSON
  • success
    optional
    boolean
  • appointment_id
    optional
    string

    UUID of the appointment row that was updated (or created).

    format: uuid
  • contact_id
    optional
    string
    format: uuid
  • created_new_appointment
    optional
    boolean

    True if the contact had no appointments, so a new row was created instead of updating one.

  • appointment_date_utc
    optional
    string

    The new appointment datetime in UTC.

    format: date-time
  • booking_timezone
    optional
    string
    or null

    IANA timezone the appointment was booked in (null when adate_utc fallback was used).

  • appointment_date_display
    optional
    string
    or null

    The human-readable display string written to the contact's appointment_date_display column.

  • contact_columns_synced
    optional
    boolean

    False if the appointments row was updated but syncing the contact's appointment_date/appointment_time/appointment_date_display columns failed (check server logs).

  • previous_appointment_date
    optional
    string
    or null

    The appointment's datetime before this update (null when a new appointment was created).

    format: date-time

400

Invalid request payload (missing identifier 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 lacks contacts.write permission

404

No contact found for the provided identifier in this workspace
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)

500

Appointment update failed (DB error)
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