Skip to content

API referenceEndpoints

Contacts

Callers and customers.

On this page

List contacts

GET/v1/contacts

Scopecontacts:read

Newest first.

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

  • phonestring

    Only the contact with this phone number (E.164; US numbers can be written without +1).

    Up to 40 characters

  • emailstring

    Only contacts with this email (not case-sensitive).

    Up to 200 characters

  • stagestring

    Only 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 ContactRequired

      This page of results.

      Contact fields
      • idstring (uuid)Required

        Contact id.

      • namestringRequired

        Name.

      • phonestringRequired

        Phone number (E.164), or empty.

      • emailstringRequired

        Email, or empty.

      • notesstringRequired

        Notes.

      • tagsarray of stringRequired

        Tags.

      • sourcestringRequired

        How they were added: call, booking, manual or api.

      • stagestringRequired

        Where they are in the funnel.

        One of: new, engaged, booked, customer, lost

      • interest_scoreinteger or nullRequired

        Latest interest score, 0 to 100.

      • categorystring or nullRequired

        What their last call was about.

      • last_summarystringRequired

        Summary of their last call.

      • next_stepstringRequired

        Suggested follow-up.

      • last_call_atstring (date-time) or nullRequired

        When they last called.

      • created_atstring (date-time)Required

        When they were added.

      • updated_atstring (date-time)Required

        When they 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/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

POST/v1/contacts

Scopecontacts: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

  • namestringRequired

    Name.

    Up to 160 characters

  • phonestring

    Phone number; E.164, or a US number in any format.

    Up to 40 characters

  • emailstring (email)

    Email, or empty.

  • notesstring

    Notes.

    Up to 5000 characters

  • tagsarray of string

    Tags.

    Up to 20 items

Responses

  • 201The contact.
    • idstring (uuid)Required

      Contact id.

    • namestringRequired

      Name.

    • phonestringRequired

      Phone number (E.164), or empty.

    • emailstringRequired

      Email, or empty.

    • notesstringRequired

      Notes.

    • tagsarray of stringRequired

      Tags.

    • sourcestringRequired

      How they were added: call, booking, manual or api.

    • stagestringRequired

      Where they are in the funnel.

      One of: new, engaged, booked, customer, lost

    • interest_scoreinteger or nullRequired

      Latest interest score, 0 to 100.

    • categorystring or nullRequired

      What their last call was about.

    • last_summarystringRequired

      Summary of their last call.

    • next_stepstringRequired

      Suggested follow-up.

    • last_call_atstring (date-time) or nullRequired

      When they last called.

    • created_atstring (date-time)Required

      When they were added.

    • updated_atstring (date-time)Required

      When they 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/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

GET/v1/contacts/{id}

Scopecontacts:read

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

Path parameters

  • idstring (uuid)Required

    The 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)Required

      Contact id.

    • namestringRequired

      Name.

    • phonestringRequired

      Phone number (E.164), or empty.

    • emailstringRequired

      Email, or empty.

    • notesstringRequired

      Notes.

    • tagsarray of stringRequired

      Tags.

    • sourcestringRequired

      How they were added: call, booking, manual or api.

    • stagestringRequired

      Where they are in the funnel.

      One of: new, engaged, booked, customer, lost

    • interest_scoreinteger or nullRequired

      Latest interest score, 0 to 100.

    • categorystring or nullRequired

      What their last call was about.

    • last_summarystringRequired

      Summary of their last call.

    • next_stepstringRequired

      Suggested follow-up.

    • last_call_atstring (date-time) or nullRequired

      When they last called.

    • created_atstring (date-time)Required

      When they were added.

    • updated_atstring (date-time)Required

      When they 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/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

PATCH/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)Required

    The 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

  • namestring

    Name.

    Up to 160 characters

  • phonestring

    Phone number, or empty to remove it.

    Up to 40 characters

  • emailstring (email)

    Email, or empty.

  • notesstring

    Notes.

    Up to 5000 characters

  • tagsarray of string

    Tags (replaces the list).

    Up to 20 items

Responses

  • 200The contact.
    • idstring (uuid)Required

      Contact id.

    • namestringRequired

      Name.

    • phonestringRequired

      Phone number (E.164), or empty.

    • emailstringRequired

      Email, or empty.

    • notesstringRequired

      Notes.

    • tagsarray of stringRequired

      Tags.

    • sourcestringRequired

      How they were added: call, booking, manual or api.

    • stagestringRequired

      Where they are in the funnel.

      One of: new, engaged, booked, customer, lost

    • interest_scoreinteger or nullRequired

      Latest interest score, 0 to 100.

    • categorystring or nullRequired

      What their last call was about.

    • last_summarystringRequired

      Summary of their last call.

    • next_stepstringRequired

      Suggested follow-up.

    • last_call_atstring (date-time) or nullRequired

      When they last called.

    • created_atstring (date-time)Required

      When they were added.

    • updated_atstring (date-time)Required

      When they 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/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"
}

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