Skip to content

API referenceEndpoints

Clients

Partner keys only: your clients' accounts.

On this page

List clients

GET/v1/clients

Scopeclients:readPartner keys

Newest first.

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

  • statusstring

    Only clients with this status.

    One of: pending_payment, onboarding, active, past_due, suspended, canceled

Responses

  • 200A page of clients.
    • dataarray of ClientRequired

      This page of results.

      Client fields
      • idstring (uuid)Required

        The client's account id (send it as AssistCall-Account).

      • namestringRequired

        Business name.

      • industrystringRequired

        Industry.

      • statusstringRequired

        Account status.

        One of: pending_payment, onboarding, active, past_due, suspended, canceled

      • packageobject or any or nullRequired

        Their package.

      • ownerobject or any or nullRequired

        The account owner.

      • numbersintegerRequired

        Active phone numbers.

      • minutes_this_periodintegerRequired

        Minutes used this billing period.

      • minutes_includedintegerRequired

        Minutes included.

      • current_period_startstring (date-time) or nullRequired

        Start of the billing period.

      • current_period_endstring (date-time) or nullRequired

        End of the billing period.

      • created_atstring (date-time)Required

        Created.

    • 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.
    • 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/clients \
  -H "Authorization: Bearer $ASSISTCALL_TOKEN"

Example response (200)

{
  "data": [
    {
      "id": "6c1f4f0e-2b7d-4c51-9a43-0d8e5b7a9f10",
      "name": "Demo Dental",
      "industry": "healthcare",
      "status": "active",
      "package": {
        "id": "4e8a2c6f-0b3d-4d5a-8f7c-9b1d3f5b7e35",
        "name": "Front Desk"
      },
      "owner": {
        "name": "Dana Rivera",
        "email": "[email protected]"
      },
      "numbers": 1,
      "minutes_this_period": 12,
      "minutes_included": 100,
      "current_period_start": "2026-10-13T00:00:00.000Z",
      "current_period_end": "2026-11-13T00:00:00.000Z",
      "created_at": "2026-09-02T17:20:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create a client

POST/v1/clients

Scopeclients:writePartner keys

Creates the account on one of your active packages, with its owner (no password yet), and emails the owner a link to set one on your portal. Manual billing: the account is served right away (onboarding). Card billing: it waits for the client's checkout (pending_payment). With setup_receptionist, it also creates the first receptionist and buys a local number. Invite emails are limited to 30 an hour (429 email_rate_limited).

Sandbox keys get 403 sandbox_read_only.

Request body

  • business_namestringRequired

    Business name.

    Up to 160 characters

  • owner_namestringRequired

    Owner's name.

    Up to 120 characters

  • owner_emailstring (email)Required

    Owner's email; their sign-in. 409 email_taken if it already has an account.

    Up to 200 characters

  • owner_phonestring

    Owner's phone.

    Up to 40 characters

  • package_idstring (uuid)Required

    One of your active packages.

  • industrystring

    Industry, e.g. healthcare.

    Up to 60 characters

  • setup_receptionistboolean

    Also create the first receptionist and buy a local number.

    Default false

Responses

  • 201The client.
    • idstring (uuid)Required

      The client's account id (send it as AssistCall-Account).

    • namestringRequired

      Business name.

    • industrystringRequired

      Industry.

    • statusstringRequired

      Account status.

      One of: pending_payment, onboarding, active, past_due, suspended, canceled

    • packageobject or any or nullRequired

      Their package.

    • ownerobject or any or nullRequired

      The account owner.

    • numbersintegerRequired

      Active phone numbers.

    • minutes_this_periodintegerRequired

      Minutes used this billing period.

    • minutes_includedintegerRequired

      Minutes included.

    • current_period_startstring (date-time) or nullRequired

      Start of the billing period.

    • current_period_endstring (date-time) or nullRequired

      End of the billing period.

    • created_atstring (date-time)Required

      Created.

    • invite_sentbooleanRequired

      Whether the set-password email went out (resend with POST /v1/clients/{id}/invite).

    • receptionist_setupobject or any or nullRequired

      Only with setup_receptionist.

    • 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.
    • 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/clients \
  -H "Authorization: Bearer $ASSISTCALL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "business_name": "Bright Smiles Dental",
  "owner_name": "Dana Rivera",
  "owner_email": "[email protected]",
  "package_id": "4e8a2c6f-0b3d-4d5a-8f7c-9b1d3f5b7e35",
  "industry": "healthcare"
}'

Example response (201)

{
  "id": "1f5b9d3a-7c2e-4f4a-9b6d-8c0e2a4c6b46",
  "name": "Bright Smiles Dental",
  "industry": "healthcare",
  "status": "onboarding",
  "package": {
    "id": "4e8a2c6f-0b3d-4d5a-8f7c-9b1d3f5b7e35",
    "name": "Front Desk"
  },
  "owner": {
    "name": "Dana Rivera",
    "email": "[email protected]"
  },
  "numbers": 0,
  "minutes_this_period": 0,
  "minutes_included": 100,
  "current_period_start": "2026-10-13T00:00:00.000Z",
  "current_period_end": "2026-11-13T00:00:00.000Z",
  "created_at": "2026-10-25T15:04:05.000Z",
  "invite_sent": true,
  "receptionist_setup": null
}

Get a client

GET/v1/clients/{id}

Scopeclients:readPartner keys

Path parameters

  • idstring (uuid)Required

    The client's id.

Responses

  • 200The client.
    • idstring (uuid)Required

      The client's account id (send it as AssistCall-Account).

    • namestringRequired

      Business name.

    • industrystringRequired

      Industry.

    • statusstringRequired

      Account status.

      One of: pending_payment, onboarding, active, past_due, suspended, canceled

    • packageobject or any or nullRequired

      Their package.

    • ownerobject or any or nullRequired

      The account owner.

    • numbersintegerRequired

      Active phone numbers.

    • minutes_this_periodintegerRequired

      Minutes used this billing period.

    • minutes_includedintegerRequired

      Minutes included.

    • current_period_startstring (date-time) or nullRequired

      Start of the billing period.

    • current_period_endstring (date-time) or nullRequired

      End of the billing period.

    • created_atstring (date-time)Required

      Created.

    • 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/clients/7d3c5a2e-9b1f-4c6a-8e2d-1f0a9b8c7d6e \
  -H "Authorization: Bearer $ASSISTCALL_TOKEN"

Example response (200)

{
  "id": "6c1f4f0e-2b7d-4c51-9a43-0d8e5b7a9f10",
  "name": "Demo Dental",
  "industry": "healthcare",
  "status": "active",
  "package": {
    "id": "4e8a2c6f-0b3d-4d5a-8f7c-9b1d3f5b7e35",
    "name": "Front Desk"
  },
  "owner": {
    "name": "Dana Rivera",
    "email": "[email protected]"
  },
  "numbers": 1,
  "minutes_this_period": 12,
  "minutes_included": 100,
  "current_period_start": "2026-10-13T00:00:00.000Z",
  "current_period_end": "2026-11-13T00:00:00.000Z",
  "created_at": "2026-09-02T17:20:00.000Z"
}

Suspend, resume or change package

PATCH/v1/clients/{id}

Scopeclients:writePartner keys

status: suspended stops the account and signs its people out; active resumes one you suspended (not one AssistCall suspended: 403). package_id moves it to another of your active packages (a card subscription moves to the new price).

Sandbox keys get 403 sandbox_read_only.

Path parameters

  • idstring (uuid)Required

    The client's id.

Request body

  • statusstring

    Suspend, or resume.

    One of: active, suspended

  • package_idstring (uuid)

    Move to another of your active packages.

Responses

  • 200The client.
    • idstring (uuid)Required

      The client's account id (send it as AssistCall-Account).

    • namestringRequired

      Business name.

    • industrystringRequired

      Industry.

    • statusstringRequired

      Account status.

      One of: pending_payment, onboarding, active, past_due, suspended, canceled

    • packageobject or any or nullRequired

      Their package.

    • ownerobject or any or nullRequired

      The account owner.

    • numbersintegerRequired

      Active phone numbers.

    • minutes_this_periodintegerRequired

      Minutes used this billing period.

    • minutes_includedintegerRequired

      Minutes included.

    • current_period_startstring (date-time) or nullRequired

      Start of the billing period.

    • current_period_endstring (date-time) or nullRequired

      End of the billing period.

    • created_atstring (date-time)Required

      Created.

    • 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 PATCH https://api.assistcall.ai/v1/clients/7d3c5a2e-9b1f-4c6a-8e2d-1f0a9b8c7d6e \
  -H "Authorization: Bearer $ASSISTCALL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "package_id": "4e8a2c6f-0b3d-4d5a-8f7c-9b1d3f5b7e35"
}'

Example response (200)

{
  "id": "6c1f4f0e-2b7d-4c51-9a43-0d8e5b7a9f10",
  "name": "Demo Dental",
  "industry": "healthcare",
  "status": "active",
  "package": {
    "id": "4e8a2c6f-0b3d-4d5a-8f7c-9b1d3f5b7e35",
    "name": "Front Desk"
  },
  "owner": {
    "name": "Dana Rivera",
    "email": "[email protected]"
  },
  "numbers": 1,
  "minutes_this_period": 12,
  "minutes_included": 100,
  "current_period_start": "2026-10-13T00:00:00.000Z",
  "current_period_end": "2026-11-13T00:00:00.000Z",
  "created_at": "2026-09-02T17:20:00.000Z"
}

Resend the owner's invite

POST/v1/clients/{id}/invite

Scopeclients:writePartner keys

Emails the owner a fresh link to set their password on your portal (it works for 3 days). The body can be empty. Limited to 30 emails an hour.

Sandbox keys get 403 sandbox_read_only.

Path parameters

  • idstring (uuid)Required

    The client's id.

Request body

object

Responses

  • 200Sent.
    • okbooleanRequired

      Always true.

    • 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/clients/7d3c5a2e-9b1f-4c6a-8e2d-1f0a9b8c7d6e/invite \
  -H "Authorization: Bearer $ASSISTCALL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Example response (200)

{
  "ok": true
}

A client's usage this period

GET/v1/clients/{id}/usage

Scopeclients:readPartner keys

Path parameters

  • idstring (uuid)Required

    The client's id.

Responses

  • 200Usage.
    • client_idstring (uuid)Required

      The client's account id.

    • period_startstring (date-time)Required

      Start of the billing period (or 30 days ago if there is none).

    • period_endstring (date-time) or nullRequired

      End of the billing period.

    • callsintegerRequired

      Calls this period.

    • minutesintegerRequired

      Minutes this period, rounded up.

    • minutes_includedintegerRequired

      Minutes included.

    • percentintegerRequired

      Share of the included minutes used, 0 to 100.

    • 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/clients/7d3c5a2e-9b1f-4c6a-8e2d-1f0a9b8c7d6e/usage \
  -H "Authorization: Bearer $ASSISTCALL_TOKEN"

Example response (200)

{
  "client_id": "6c1f4f0e-2b7d-4c51-9a43-0d8e5b7a9f10",
  "period_start": "2026-10-13T00:00:00.000Z",
  "period_end": "2026-11-13T00:00:00.000Z",
  "calls": 6,
  "minutes": 12,
  "minutes_included": 100,
  "percent": 12
}

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