API referenceEndpoints
Contacts
Callers and customers.
List contacts
/v1/contactsScopecontacts:read
Newest first.
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
phonestringOnly the contact with this phone number (E.164; US numbers can be written without +1).
Up to 40 characters
emailstringOnly contacts with this email (not case-sensitive).
Up to 200 characters
stagestringOnly contacts at this stage.
One of:
new,engaged,booked,customer,lost
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 contacts.
dataarray of ContactRequiredThis page of results.
Contact fields
idstring (uuid)RequiredContact id.
namestringRequiredName.
phonestringRequiredPhone number (E.164), or empty.
emailstringRequiredEmail, or empty.
notesstringRequiredNotes.
tagsarray of stringRequiredTags.
sourcestringRequiredHow they were added:
call,booking,manualorapi.stagestringRequiredWhere they are in the funnel.
One of:
new,engaged,booked,customer,lostinterest_scoreinteger or nullRequiredLatest interest score, 0 to 100.
categorystring or nullRequiredWhat their last call was about.
last_summarystringRequiredSummary of their last call.
next_stepstringRequiredSuggested follow-up.
last_call_atstring (date-time) or nullRequiredWhen they last called.
created_atstring (date-time)RequiredWhen they were added.
updated_atstring (date-time)RequiredWhen they 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/contacts \
-H "Authorization: Bearer $ASSISTCALL_TOKEN"Example response (200)
{
"data": [
{
"id": "e5c9a3f7-2d4b-4c6e-8f0a-3b5d7f9c1e57",
"name": "Maria Lopez",
"phone": "+12125550147",
"email": "[email protected]",
"notes": "",
"tags": [
"new-patient"
],
"source": "call",
"stage": "booked",
"interest_score": 86,
"category": "appointment",
"last_summary": "Booked a cleaning and exam for Thursday at 10:00 AM.",
"next_step": "Confirm insurance before the visit.",
"last_call_at": "2026-10-25T13:29:12.000Z",
"created_at": "2026-10-25T13:29:12.000Z",
"updated_at": "2026-10-25T13:32:16.000Z"
}
],
"has_more": false,
"next_cursor": null
}Add a contact
/v1/contactsScopecontacts:write
A phone number belongs to one contact per account: adding a second gets 409 contact_exists.
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
namestringRequiredName.
Up to 160 characters
phonestringPhone number; E.164, or a US number in any format.
Up to 40 characters
emailstring (email)Email, or empty.
notesstringNotes.
Up to 5000 characters
tagsarray of stringTags.
Up to 20 items
Responses
201The contact.
idstring (uuid)RequiredContact id.
namestringRequiredName.
phonestringRequiredPhone number (E.164), or empty.
emailstringRequiredEmail, or empty.
notesstringRequiredNotes.
tagsarray of stringRequiredTags.
sourcestringRequiredHow they were added:
call,booking,manualorapi.stagestringRequiredWhere they are in the funnel.
One of:
new,engaged,booked,customer,lostinterest_scoreinteger or nullRequiredLatest interest score, 0 to 100.
categorystring or nullRequiredWhat their last call was about.
last_summarystringRequiredSummary of their last call.
next_stepstringRequiredSuggested follow-up.
last_call_atstring (date-time) or nullRequiredWhen they last called.
created_atstring (date-time)RequiredWhen they were added.
updated_atstring (date-time)RequiredWhen they 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/contacts \
-H "Authorization: Bearer $ASSISTCALL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Dana Rivera",
"phone": "(212) 555-0199",
"email": "[email protected]",
"tags": [
"referral"
]
}'Example response (201)
{
"id": "e5c9a3f7-2d4b-4c6e-8f0a-3b5d7f9c1e57",
"name": "Dana Rivera",
"phone": "+12125550199",
"email": "[email protected]",
"notes": "",
"tags": [
"referral"
],
"source": "api",
"stage": "new",
"interest_score": null,
"category": null,
"last_summary": "",
"next_step": "",
"last_call_at": null,
"created_at": "2026-10-25T13:29:12.000Z",
"updated_at": "2026-10-25T13:32:16.000Z"
}Get a contact
/v1/contacts/{id}Scopecontacts:read
Partner keys send the client's account id in AssistCall-Account.
Path parameters
idstring (uuid)RequiredThe contact'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 contact.
idstring (uuid)RequiredContact id.
namestringRequiredName.
phonestringRequiredPhone number (E.164), or empty.
emailstringRequiredEmail, or empty.
notesstringRequiredNotes.
tagsarray of stringRequiredTags.
sourcestringRequiredHow they were added:
call,booking,manualorapi.stagestringRequiredWhere they are in the funnel.
One of:
new,engaged,booked,customer,lostinterest_scoreinteger or nullRequiredLatest interest score, 0 to 100.
categorystring or nullRequiredWhat their last call was about.
last_summarystringRequiredSummary of their last call.
next_stepstringRequiredSuggested follow-up.
last_call_atstring (date-time) or nullRequiredWhen they last called.
created_atstring (date-time)RequiredWhen they were added.
updated_atstring (date-time)RequiredWhen they 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/contacts/7d3c5a2e-9b1f-4c6a-8e2d-1f0a9b8c7d6e \
-H "Authorization: Bearer $ASSISTCALL_TOKEN"Example response (200)
{
"id": "e5c9a3f7-2d4b-4c6e-8f0a-3b5d7f9c1e57",
"name": "Maria Lopez",
"phone": "+12125550147",
"email": "[email protected]",
"notes": "",
"tags": [
"new-patient"
],
"source": "call",
"stage": "booked",
"interest_score": 86,
"category": "appointment",
"last_summary": "Booked a cleaning and exam for Thursday at 10:00 AM.",
"next_step": "Confirm insurance before the visit.",
"last_call_at": "2026-10-25T13:29:12.000Z",
"created_at": "2026-10-25T13:29:12.000Z",
"updated_at": "2026-10-25T13:32:16.000Z"
}Edit a contact
/v1/contacts/{id}Scopecontacts:write
Only the fields you send change. tags replaces the list.
Partner keys send the client's account id in AssistCall-Account.
Sandbox keys get 403 sandbox_read_only.
Path parameters
idstring (uuid)RequiredThe contact'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
namestringName.
Up to 160 characters
phonestringPhone number, or empty to remove it.
Up to 40 characters
emailstring (email)Email, or empty.
notesstringNotes.
Up to 5000 characters
tagsarray of stringTags (replaces the list).
Up to 20 items
Responses
200The contact.
idstring (uuid)RequiredContact id.
namestringRequiredName.
phonestringRequiredPhone number (E.164), or empty.
emailstringRequiredEmail, or empty.
notesstringRequiredNotes.
tagsarray of stringRequiredTags.
sourcestringRequiredHow they were added:
call,booking,manualorapi.stagestringRequiredWhere they are in the funnel.
One of:
new,engaged,booked,customer,lostinterest_scoreinteger or nullRequiredLatest interest score, 0 to 100.
categorystring or nullRequiredWhat their last call was about.
last_summarystringRequiredSummary of their last call.
next_stepstringRequiredSuggested follow-up.
last_call_atstring (date-time) or nullRequiredWhen they last called.
created_atstring (date-time)RequiredWhen they were added.
updated_atstring (date-time)RequiredWhen they 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/contacts/7d3c5a2e-9b1f-4c6a-8e2d-1f0a9b8c7d6e \
-H "Authorization: Bearer $ASSISTCALL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"notes": "Prefers morning appointments.",
"tags": [
"new-patient",
"mornings"
]
}'Example response (200)
{
"id": "e5c9a3f7-2d4b-4c6e-8f0a-3b5d7f9c1e57",
"name": "Maria Lopez",
"phone": "+12125550147",
"email": "[email protected]",
"notes": "Prefers morning appointments.",
"tags": [
"new-patient",
"mornings"
],
"source": "call",
"stage": "booked",
"interest_score": 86,
"category": "appointment",
"last_summary": "Booked a cleaning and exam for Thursday at 10:00 AM.",
"next_step": "Confirm insurance before the visit.",
"last_call_at": "2026-10-25T13:29:12.000Z",
"created_at": "2026-10-25T13:29:12.000Z",
"updated_at": "2026-10-25T13:32:16.000Z"
}