Skip to content

API referenceEndpoints

Appointments

Bookings, from calls, the booking page, the portal or the API.

On this page

List appointments

GET/v1/appointments

Scopeappointments:read

Soonest first (by starts_at).

Partner keys send the client's account id in AssistCall-Account.

Query parameters

  • limitinteger

    How many items to return, 1 to 100.

    Default 251 to 100

  • cursorstring

    The next_cursor of the previous page.

    Up to 300 characters

  • starts_afterstring (date-time)

    Only appointments starting at or after this time, e.g. now for upcoming ones.

  • starts_beforestring (date-time)

    Only appointments starting before this time.

  • statusstring

    Only appointments with this status.

    One of: scheduled, confirmed, completed, canceled, no_show

  • contact_idstring (uuid)

    Only this contact's appointments.

Headers

  • AssistCall-Accountstring (uuid)

    Partner keys: required. The account id of one of your clients; any other id gets 404. Client keys: optional, and must be the key's own account.

Responses

  • 200A page of appointments.
    • dataarray of AppointmentRequired

      This page of results.

      Appointment fields
      • idstring (uuid)Required

        Appointment id.

      • contact_idstring (uuid) or nullRequired

        The person's contact.

      • call_idstring (uuid) or nullRequired

        The call it was booked on.

      • namestringRequired

        Who the appointment is with.

      • phonestringRequired

        Their phone number.

      • emailstringRequired

        Their email.

      • starts_atstring (date-time)Required

        Start time.

      • duration_minintegerRequired

        Length in minutes.

      • statusstringRequired

        Status.

        One of: scheduled, confirmed, completed, canceled, no_show

      • reasonstringRequired

        What it's for.

      • notesstringRequired

        Internal notes.

      • sourcestringRequired

        ai: booked on a call; booking: the booking page; manual: the portal or the API.

        One of: manual, ai, booking

      • created_atstring (date-time)Required

        When it was booked.

      • updated_atstring (date-time)Required

        When it last changed.

    • has_morebooleanRequired

      Whether there are more results after this page.

    • next_cursorstring or nullRequired

      Pass as cursor to get the next page; null on the last page.

    • 400invalid_requestA parameter or body field is missing or invalid; the message names it.
    • 401authenticationNo access token, or it’s invalid or expired (or, at the token endpoint, wrong client credentials).
    • 403permissionThe token lacks the scope, the IP isn’t allowed, the account isn’t active, or a sandbox key tried to write.
    • 404not_foundNo such object in this account (ids from other accounts are “not found” too).
    • 429rate_limitToo many requests: wait Retry-After seconds.
    • 500serverSomething went wrong on our side. Retry with backoff.

    Errors share one shape. See Errors.

Example request

curl https://api.assistcall.ai/v1/appointments \
  -H "Authorization: Bearer $ASSISTCALL_TOKEN"

Example response (200)

{
  "data": [
    {
      "id": "c8a2e6f0-4b9d-4d1c-a3e5-7f9b1d3f5a79",
      "contact_id": "e5c9a3f7-2d4b-4c6e-8f0a-3b5d7f9c1e57",
      "call_id": "3a7e9c15-6d2b-4f40-8e1a-5b9c7d3e1f24",
      "name": "Maria Lopez",
      "phone": "+12125550147",
      "email": "[email protected]",
      "starts_at": "2026-10-29T14:00:00.000Z",
      "duration_min": 60,
      "status": "scheduled",
      "reason": "New patient cleaning and exam",
      "notes": "",
      "source": "ai",
      "created_at": "2026-10-25T13:32:16.000Z",
      "updated_at": "2026-10-25T13:32:16.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Book an appointment

POST/v1/appointments

Scopeappointments:write

Books like the team does in the portal: outside open hours is fine, on top of another appointment isn't (409 slot_taken). With notify, the person gets a confirmation email with links to reschedule or cancel (at most 30 booking emails an hour per account through the API: 429 email_rate_limited). Sends the appointment.booked event.

Partner keys send the client's account id in AssistCall-Account.

Sandbox keys get 403 sandbox_read_only.

Headers

  • AssistCall-Accountstring (uuid)

    Partner keys: required. The account id of one of your clients; any other id gets 404. Client keys: optional, and must be the key's own account.

Request body

  • namestringRequired

    Who the appointment is with.

    Up to 160 characters

  • phonestring

    Their phone number; links the appointment to their contact (created if new).

    Up to 40 characters

  • emailstring (email)

    Their email, or empty.

    Up to 320 characters

  • starts_atstring (date-time)Required

    Start time, ISO 8601 with an offset.

  • duration_mininteger

    Length in minutes. Default: the booking page's length.

    5 to 480

  • statusstring

    Status.

    One of: scheduled, confirmedDefault scheduled

  • reasonstring

    What it's for.

    Up to 500 characters

  • notesstring

    Internal notes.

    Up to 5000 characters

  • notifyboolean

    Email the person a confirmation (when there's an email).

    Default false

Responses

  • 201The appointment.
    • idstring (uuid)Required

      Appointment id.

    • contact_idstring (uuid) or nullRequired

      The person's contact.

    • call_idstring (uuid) or nullRequired

      The call it was booked on.

    • namestringRequired

      Who the appointment is with.

    • phonestringRequired

      Their phone number.

    • emailstringRequired

      Their email.

    • starts_atstring (date-time)Required

      Start time.

    • duration_minintegerRequired

      Length in minutes.

    • statusstringRequired

      Status.

      One of: scheduled, confirmed, completed, canceled, no_show

    • reasonstringRequired

      What it's for.

    • notesstringRequired

      Internal notes.

    • sourcestringRequired

      ai: booked on a call; booking: the booking page; manual: the portal or the API.

      One of: manual, ai, booking

    • created_atstring (date-time)Required

      When it was booked.

    • updated_atstring (date-time)Required

      When it last changed.

    • 400invalid_requestA parameter or body field is missing or invalid; the message names it.
    • 401authenticationNo access token, or it’s invalid or expired (or, at the token endpoint, wrong client credentials).
    • 403permissionThe token lacks the scope, the IP isn’t allowed, the account isn’t active, or a sandbox key tried to write.
    • 404not_foundNo such object in this account (ids from other accounts are “not found” too).
    • 409conflictIt conflicts with something that already exists.
    • 429rate_limitToo many requests: wait Retry-After seconds.
    • 500serverSomething went wrong on our side. Retry with backoff.

    Errors share one shape. See Errors.

Example request

curl -X POST https://api.assistcall.ai/v1/appointments \
  -H "Authorization: Bearer $ASSISTCALL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Maria Lopez",
  "phone": "+12125550147",
  "email": "[email protected]",
  "starts_at": "2026-10-29T10:00:00-04:00",
  "duration_min": 60,
  "reason": "Cleaning and exam",
  "notify": true
}'

Example response (201)

{
  "id": "c8a2e6f0-4b9d-4d1c-a3e5-7f9b1d3f5a79",
  "contact_id": "e5c9a3f7-2d4b-4c6e-8f0a-3b5d7f9c1e57",
  "call_id": null,
  "name": "Maria Lopez",
  "phone": "+12125550147",
  "email": "[email protected]",
  "starts_at": "2026-10-29T14:00:00.000Z",
  "duration_min": 60,
  "status": "scheduled",
  "reason": "New patient cleaning and exam",
  "notes": "",
  "source": "manual",
  "created_at": "2026-10-25T13:32:16.000Z",
  "updated_at": "2026-10-25T13:32:16.000Z"
}

Get an appointment

GET/v1/appointments/{id}

Scopeappointments:read

Partner keys send the client's account id in AssistCall-Account.

Path parameters

  • idstring (uuid)Required

    The appointment's id.

Headers

  • AssistCall-Accountstring (uuid)

    Partner keys: required. The account id of one of your clients; any other id gets 404. Client keys: optional, and must be the key's own account.

Responses

  • 200The appointment.
    • idstring (uuid)Required

      Appointment id.

    • contact_idstring (uuid) or nullRequired

      The person's contact.

    • call_idstring (uuid) or nullRequired

      The call it was booked on.

    • namestringRequired

      Who the appointment is with.

    • phonestringRequired

      Their phone number.

    • emailstringRequired

      Their email.

    • starts_atstring (date-time)Required

      Start time.

    • duration_minintegerRequired

      Length in minutes.

    • statusstringRequired

      Status.

      One of: scheduled, confirmed, completed, canceled, no_show

    • reasonstringRequired

      What it's for.

    • notesstringRequired

      Internal notes.

    • sourcestringRequired

      ai: booked on a call; booking: the booking page; manual: the portal or the API.

      One of: manual, ai, booking

    • created_atstring (date-time)Required

      When it was booked.

    • updated_atstring (date-time)Required

      When it last changed.

    • 400invalid_requestA parameter or body field is missing or invalid; the message names it.
    • 401authenticationNo access token, or it’s invalid or expired (or, at the token endpoint, wrong client credentials).
    • 403permissionThe token lacks the scope, the IP isn’t allowed, the account isn’t active, or a sandbox key tried to write.
    • 404not_foundNo such object in this account (ids from other accounts are “not found” too).
    • 429rate_limitToo many requests: wait Retry-After seconds.
    • 500serverSomething went wrong on our side. Retry with backoff.

    Errors share one shape. See Errors.

Example request

curl https://api.assistcall.ai/v1/appointments/7d3c5a2e-9b1f-4c6a-8e2d-1f0a9b8c7d6e \
  -H "Authorization: Bearer $ASSISTCALL_TOKEN"

Example response (200)

{
  "id": "c8a2e6f0-4b9d-4d1c-a3e5-7f9b1d3f5a79",
  "contact_id": "e5c9a3f7-2d4b-4c6e-8f0a-3b5d7f9c1e57",
  "call_id": "3a7e9c15-6d2b-4f40-8e1a-5b9c7d3e1f24",
  "name": "Maria Lopez",
  "phone": "+12125550147",
  "email": "[email protected]",
  "starts_at": "2026-10-29T14:00:00.000Z",
  "duration_min": 60,
  "status": "scheduled",
  "reason": "New patient cleaning and exam",
  "notes": "",
  "source": "ai",
  "created_at": "2026-10-25T13:32:16.000Z",
  "updated_at": "2026-10-25T13:32:16.000Z"
}

Change an appointment

PATCH/v1/appointments/{id}

Scopeappointments:write

Only the fields you send change. A new starts_at or duration_min reschedules it (409 slot_taken if that overlaps another appointment) and sends appointment.rescheduled; status canceled sends appointment.canceled. With notify, the person is emailed about a new time or a cancellation (counts toward the 30 booking emails an hour per account: 429 email_rate_limited).

Partner keys send the client's account id in AssistCall-Account.

Sandbox keys get 403 sandbox_read_only.

Path parameters

  • idstring (uuid)Required

    The appointment's id.

Headers

  • AssistCall-Accountstring (uuid)

    Partner keys: required. The account id of one of your clients; any other id gets 404. Client keys: optional, and must be the key's own account.

Request body

  • namestring

    Who the appointment is with.

    Up to 160 characters

  • phonestring

    Phone number.

    Up to 40 characters

  • emailstring (email)

    Email, or empty.

  • starts_atstring (date-time)

    New start time (reschedules).

  • duration_mininteger

    New length in minutes.

    5 to 480

  • statusstring

    New status.

    One of: scheduled, confirmed, completed, canceled, no_show

  • reasonstring

    What it's for.

    Up to 500 characters

  • notesstring

    Internal notes.

    Up to 5000 characters

  • notifyboolean

    Email the person about a new time or a cancellation.

    Default false

Responses

  • 200The appointment.
    • idstring (uuid)Required

      Appointment id.

    • contact_idstring (uuid) or nullRequired

      The person's contact.

    • call_idstring (uuid) or nullRequired

      The call it was booked on.

    • namestringRequired

      Who the appointment is with.

    • phonestringRequired

      Their phone number.

    • emailstringRequired

      Their email.

    • starts_atstring (date-time)Required

      Start time.

    • duration_minintegerRequired

      Length in minutes.

    • statusstringRequired

      Status.

      One of: scheduled, confirmed, completed, canceled, no_show

    • reasonstringRequired

      What it's for.

    • notesstringRequired

      Internal notes.

    • sourcestringRequired

      ai: booked on a call; booking: the booking page; manual: the portal or the API.

      One of: manual, ai, booking

    • created_atstring (date-time)Required

      When it was booked.

    • updated_atstring (date-time)Required

      When it last changed.

    • 400invalid_requestA parameter or body field is missing or invalid; the message names it.
    • 401authenticationNo access token, or it’s invalid or expired (or, at the token endpoint, wrong client credentials).
    • 403permissionThe token lacks the scope, the IP isn’t allowed, the account isn’t active, or a sandbox key tried to write.
    • 404not_foundNo such object in this account (ids from other accounts are “not found” too).
    • 409conflictIt conflicts with something that already exists.
    • 429rate_limitToo many requests: wait Retry-After seconds.
    • 500serverSomething went wrong on our side. Retry with backoff.

    Errors share one shape. See Errors.

Example request

curl -X PATCH https://api.assistcall.ai/v1/appointments/7d3c5a2e-9b1f-4c6a-8e2d-1f0a9b8c7d6e \
  -H "Authorization: Bearer $ASSISTCALL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "starts_at": "2026-10-30T15:00:00-04:00",
  "notify": true
}'

Example response (200)

{
  "id": "c8a2e6f0-4b9d-4d1c-a3e5-7f9b1d3f5a79",
  "contact_id": "e5c9a3f7-2d4b-4c6e-8f0a-3b5d7f9c1e57",
  "call_id": "3a7e9c15-6d2b-4f40-8e1a-5b9c7d3e1f24",
  "name": "Maria Lopez",
  "phone": "+12125550147",
  "email": "[email protected]",
  "starts_at": "2026-10-30T19:00:00.000Z",
  "duration_min": 60,
  "status": "scheduled",
  "reason": "New patient cleaning and exam",
  "notes": "",
  "source": "ai",
  "created_at": "2026-10-25T13:32:16.000Z",
  "updated_at": "2026-10-25T13:32:16.000Z"
}

Cancel an appointment

POST/v1/appointments/{id}/cancel

Scopeappointments:write

Sets the status to canceled and sends appointment.canceled. Canceling one that is already canceled changes nothing. The body can be empty.

Partner keys send the client's account id in AssistCall-Account.

Sandbox keys get 403 sandbox_read_only.

Path parameters

  • idstring (uuid)Required

    The appointment's id.

Headers

  • AssistCall-Accountstring (uuid)

    Partner keys: required. The account id of one of your clients; any other id gets 404. Client keys: optional, and must be the key's own account.

Request body

  • notifyboolean

    Email the person that it's canceled.

    Default false

Responses

  • 200The appointment.
    • idstring (uuid)Required

      Appointment id.

    • contact_idstring (uuid) or nullRequired

      The person's contact.

    • call_idstring (uuid) or nullRequired

      The call it was booked on.

    • namestringRequired

      Who the appointment is with.

    • phonestringRequired

      Their phone number.

    • emailstringRequired

      Their email.

    • starts_atstring (date-time)Required

      Start time.

    • duration_minintegerRequired

      Length in minutes.

    • statusstringRequired

      Status.

      One of: scheduled, confirmed, completed, canceled, no_show

    • reasonstringRequired

      What it's for.

    • notesstringRequired

      Internal notes.

    • sourcestringRequired

      ai: booked on a call; booking: the booking page; manual: the portal or the API.

      One of: manual, ai, booking

    • created_atstring (date-time)Required

      When it was booked.

    • updated_atstring (date-time)Required

      When it last changed.

    • 400invalid_requestA parameter or body field is missing or invalid; the message names it.
    • 401authenticationNo access token, or it’s invalid or expired (or, at the token endpoint, wrong client credentials).
    • 403permissionThe token lacks the scope, the IP isn’t allowed, the account isn’t active, or a sandbox key tried to write.
    • 404not_foundNo such object in this account (ids from other accounts are “not found” too).
    • 429rate_limitToo many requests: wait Retry-After seconds.
    • 500serverSomething went wrong on our side. Retry with backoff.

    Errors share one shape. See Errors.

Example request

curl -X POST https://api.assistcall.ai/v1/appointments/7d3c5a2e-9b1f-4c6a-8e2d-1f0a9b8c7d6e/cancel \
  -H "Authorization: Bearer $ASSISTCALL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "notify": true
}'

Example response (200)

{
  "id": "c8a2e6f0-4b9d-4d1c-a3e5-7f9b1d3f5a79",
  "contact_id": "e5c9a3f7-2d4b-4c6e-8f0a-3b5d7f9c1e57",
  "call_id": "3a7e9c15-6d2b-4f40-8e1a-5b9c7d3e1f24",
  "name": "Maria Lopez",
  "phone": "+12125550147",
  "email": "[email protected]",
  "starts_at": "2026-10-29T14:00:00.000Z",
  "duration_min": 60,
  "status": "canceled",
  "reason": "New patient cleaning and exam",
  "notes": "",
  "source": "ai",
  "created_at": "2026-10-25T13:32:16.000Z",
  "updated_at": "2026-10-25T13:32:16.000Z"
}

Try "token", "webhook signature", "rate limit" or "custom domain".