API referenceEndpoints
Appointments
Bookings, from calls, the booking page, the portal or the API.
On this page
List appointments
/v1/appointmentsScopeappointments:read
Soonest first (by starts_at).
Partner keys send the client's account id in AssistCall-Account.
Query parameters
limitintegerHow many items to return, 1 to 100.
Default
251 to 100cursorstringThe
next_cursorof 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.
statusstringOnly appointments with this status.
One of:
scheduled,confirmed,completed,canceled,no_showcontact_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 AppointmentRequiredThis page of results.
Appointment fields
idstring (uuid)RequiredAppointment id.
contact_idstring (uuid) or nullRequiredThe person's contact.
call_idstring (uuid) or nullRequiredThe call it was booked on.
namestringRequiredWho the appointment is with.
phonestringRequiredTheir phone number.
emailstringRequiredTheir email.
starts_atstring (date-time)RequiredStart time.
duration_minintegerRequiredLength in minutes.
statusstringRequiredStatus.
One of:
scheduled,confirmed,completed,canceled,no_showreasonstringRequiredWhat it's for.
notesstringRequiredInternal notes.
sourcestringRequiredai: booked on a call;booking: the booking page;manual: the portal or the API.One of:
manual,ai,bookingcreated_atstring (date-time)RequiredWhen it was booked.
updated_atstring (date-time)RequiredWhen it last changed.
has_morebooleanRequiredWhether there are more results after this page.
next_cursorstring or nullRequiredPass as
cursorto get the next page; null on the last page.
- 400
invalid_requestA parameter or body field is missing or invalid; the message names it. - 401
authenticationNo access token, or it’s invalid or expired (or, at the token endpoint, wrong client credentials). - 403
permissionThe token lacks the scope, the IP isn’t allowed, the account isn’t active, or a sandbox key tried to write. - 404
not_foundNo such object in this account (ids from other accounts are “not found” too). - 429
rate_limitToo many requests: wait Retry-After seconds. - 500
serverSomething went wrong on our side. Retry with backoff.
Errors share one shape. See Errors.
- 400
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
/v1/appointmentsScopeappointments: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
namestringRequiredWho the appointment is with.
Up to 160 characters
phonestringTheir 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)RequiredStart time, ISO 8601 with an offset.
duration_minintegerLength in minutes. Default: the booking page's length.
5 to 480
statusstringStatus.
One of:
scheduled,confirmedDefaultscheduledreasonstringWhat it's for.
Up to 500 characters
notesstringInternal notes.
Up to 5000 characters
notifybooleanEmail the person a confirmation (when there's an email).
Default
false
Responses
201The appointment.
idstring (uuid)RequiredAppointment id.
contact_idstring (uuid) or nullRequiredThe person's contact.
call_idstring (uuid) or nullRequiredThe call it was booked on.
namestringRequiredWho the appointment is with.
phonestringRequiredTheir phone number.
emailstringRequiredTheir email.
starts_atstring (date-time)RequiredStart time.
duration_minintegerRequiredLength in minutes.
statusstringRequiredStatus.
One of:
scheduled,confirmed,completed,canceled,no_showreasonstringRequiredWhat it's for.
notesstringRequiredInternal notes.
sourcestringRequiredai: booked on a call;booking: the booking page;manual: the portal or the API.One of:
manual,ai,bookingcreated_atstring (date-time)RequiredWhen it was booked.
updated_atstring (date-time)RequiredWhen it last changed.
- 400
invalid_requestA parameter or body field is missing or invalid; the message names it. - 401
authenticationNo access token, or it’s invalid or expired (or, at the token endpoint, wrong client credentials). - 403
permissionThe token lacks the scope, the IP isn’t allowed, the account isn’t active, or a sandbox key tried to write. - 404
not_foundNo such object in this account (ids from other accounts are “not found” too). - 409
conflictIt conflicts with something that already exists. - 429
rate_limitToo many requests: wait Retry-After seconds. - 500
serverSomething went wrong on our side. Retry with backoff.
Errors share one shape. See Errors.
- 400
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
/v1/appointments/{id}Scopeappointments:read
Partner keys send the client's account id in AssistCall-Account.
Path parameters
idstring (uuid)RequiredThe 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)RequiredAppointment id.
contact_idstring (uuid) or nullRequiredThe person's contact.
call_idstring (uuid) or nullRequiredThe call it was booked on.
namestringRequiredWho the appointment is with.
phonestringRequiredTheir phone number.
emailstringRequiredTheir email.
starts_atstring (date-time)RequiredStart time.
duration_minintegerRequiredLength in minutes.
statusstringRequiredStatus.
One of:
scheduled,confirmed,completed,canceled,no_showreasonstringRequiredWhat it's for.
notesstringRequiredInternal notes.
sourcestringRequiredai: booked on a call;booking: the booking page;manual: the portal or the API.One of:
manual,ai,bookingcreated_atstring (date-time)RequiredWhen it was booked.
updated_atstring (date-time)RequiredWhen it last changed.
- 400
invalid_requestA parameter or body field is missing or invalid; the message names it. - 401
authenticationNo access token, or it’s invalid or expired (or, at the token endpoint, wrong client credentials). - 403
permissionThe token lacks the scope, the IP isn’t allowed, the account isn’t active, or a sandbox key tried to write. - 404
not_foundNo such object in this account (ids from other accounts are “not found” too). - 429
rate_limitToo many requests: wait Retry-After seconds. - 500
serverSomething went wrong on our side. Retry with backoff.
Errors share one shape. See Errors.
- 400
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
/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)RequiredThe 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
namestringWho the appointment is with.
Up to 160 characters
phonestringPhone number.
Up to 40 characters
emailstring (email)Email, or empty.
starts_atstring (date-time)New start time (reschedules).
duration_minintegerNew length in minutes.
5 to 480
statusstringNew status.
One of:
scheduled,confirmed,completed,canceled,no_showreasonstringWhat it's for.
Up to 500 characters
notesstringInternal notes.
Up to 5000 characters
notifybooleanEmail the person about a new time or a cancellation.
Default
false
Responses
200The appointment.
idstring (uuid)RequiredAppointment id.
contact_idstring (uuid) or nullRequiredThe person's contact.
call_idstring (uuid) or nullRequiredThe call it was booked on.
namestringRequiredWho the appointment is with.
phonestringRequiredTheir phone number.
emailstringRequiredTheir email.
starts_atstring (date-time)RequiredStart time.
duration_minintegerRequiredLength in minutes.
statusstringRequiredStatus.
One of:
scheduled,confirmed,completed,canceled,no_showreasonstringRequiredWhat it's for.
notesstringRequiredInternal notes.
sourcestringRequiredai: booked on a call;booking: the booking page;manual: the portal or the API.One of:
manual,ai,bookingcreated_atstring (date-time)RequiredWhen it was booked.
updated_atstring (date-time)RequiredWhen it last changed.
- 400
invalid_requestA parameter or body field is missing or invalid; the message names it. - 401
authenticationNo access token, or it’s invalid or expired (or, at the token endpoint, wrong client credentials). - 403
permissionThe token lacks the scope, the IP isn’t allowed, the account isn’t active, or a sandbox key tried to write. - 404
not_foundNo such object in this account (ids from other accounts are “not found” too). - 409
conflictIt conflicts with something that already exists. - 429
rate_limitToo many requests: wait Retry-After seconds. - 500
serverSomething went wrong on our side. Retry with backoff.
Errors share one shape. See Errors.
- 400
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
/v1/appointments/{id}/cancelScopeappointments: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)RequiredThe 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
notifybooleanEmail the person that it's canceled.
Default
false
Responses
200The appointment.
idstring (uuid)RequiredAppointment id.
contact_idstring (uuid) or nullRequiredThe person's contact.
call_idstring (uuid) or nullRequiredThe call it was booked on.
namestringRequiredWho the appointment is with.
phonestringRequiredTheir phone number.
emailstringRequiredTheir email.
starts_atstring (date-time)RequiredStart time.
duration_minintegerRequiredLength in minutes.
statusstringRequiredStatus.
One of:
scheduled,confirmed,completed,canceled,no_showreasonstringRequiredWhat it's for.
notesstringRequiredInternal notes.
sourcestringRequiredai: booked on a call;booking: the booking page;manual: the portal or the API.One of:
manual,ai,bookingcreated_atstring (date-time)RequiredWhen it was booked.
updated_atstring (date-time)RequiredWhen it last changed.
- 400
invalid_requestA parameter or body field is missing or invalid; the message names it. - 401
authenticationNo access token, or it’s invalid or expired (or, at the token endpoint, wrong client credentials). - 403
permissionThe token lacks the scope, the IP isn’t allowed, the account isn’t active, or a sandbox key tried to write. - 404
not_foundNo such object in this account (ids from other accounts are “not found” too). - 429
rate_limitToo many requests: wait Retry-After seconds. - 500
serverSomething went wrong on our side. Retry with backoff.
Errors share one shape. See Errors.
- 400
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"
}