Skip to content

API referenceEndpoints

Receptionists

Receptionists and their phone numbers.

On this page

List receptionists

GET/v1/receptionists

Scopereceptionists:read

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

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 receptionists.
    • dataarray of ReceptionistRequired

      This page of results.

      Receptionist fields
      • idstring (uuid)Required

        Receptionist id.

      • namestringRequired

        Name.

      • statusstringRequired

        Status.

        One of: active, paused

      • voiceobjectRequired
        Fields
        • providerstringRequired

          Voice provider.

        • idstringRequired

          Voice id.

      • greetingstringRequired

        What it says when it answers.

      • transfer_numberstringRequired

        Where it transfers callers, or empty.

      • booking_enabledbooleanRequired

        Whether it books appointments.

      • messages_enabledbooleanRequired

        Whether it takes messages.

      • numbersarray of PhoneNumberRequired

        Numbers it answers.

        PhoneNumber fields
        • idstring (uuid)Required

          Number id.

        • numberstringRequired

          The number (E.164).

        • namestringRequired

          Its label.

        • receptionist_idstring (uuid) or nullRequired

          The receptionist answering it.

        • created_atstring (date-time)Required

          Added.

      • created_atstring (date-time)Required

        Created.

      • updated_atstring (date-time)Required

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

Example response (200)

{
  "data": [
    {
      "id": "d4b8f2a6-1c3e-4a5b-9d7f-8e6c4a2b0d35",
      "name": "Mia",
      "status": "active",
      "voice": {
        "provider": "openai",
        "id": "marin"
      },
      "greeting": "Thanks for calling Demo Dental! This is Mia. How can I help you today?",
      "transfer_number": "",
      "booking_enabled": true,
      "messages_enabled": true,
      "numbers": [
        {
          "id": "7f3c1e5a-9b2d-4e6f-a8c0-1d3b5f7e9a46",
          "number": "+12125550101",
          "name": "Demo Dental",
          "receptionist_id": "d4b8f2a6-1c3e-4a5b-9d7f-8e6c4a2b0d35",
          "created_at": "2026-09-02T17:20:00.000Z"
        }
      ],
      "created_at": "2026-09-02T17:20:00.000Z",
      "updated_at": "2026-09-02T17:20:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Get a receptionist

GET/v1/receptionists/{id}

Scopereceptionists:read

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

Path parameters

  • idstring (uuid)Required

    The receptionist'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 receptionist.
    • idstring (uuid)Required

      Receptionist id.

    • namestringRequired

      Name.

    • statusstringRequired

      Status.

      One of: active, paused

    • voiceobjectRequired
      Fields
      • providerstringRequired

        Voice provider.

      • idstringRequired

        Voice id.

    • greetingstringRequired

      What it says when it answers.

    • transfer_numberstringRequired

      Where it transfers callers, or empty.

    • booking_enabledbooleanRequired

      Whether it books appointments.

    • messages_enabledbooleanRequired

      Whether it takes messages.

    • numbersarray of PhoneNumberRequired

      Numbers it answers.

      PhoneNumber fields
      • idstring (uuid)Required

        Number id.

      • numberstringRequired

        The number (E.164).

      • namestringRequired

        Its label.

      • receptionist_idstring (uuid) or nullRequired

        The receptionist answering it.

      • created_atstring (date-time)Required

        Added.

    • created_atstring (date-time)Required

      Created.

    • updated_atstring (date-time)Required

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

Example response (200)

{
  "id": "d4b8f2a6-1c3e-4a5b-9d7f-8e6c4a2b0d35",
  "name": "Mia",
  "status": "active",
  "voice": {
    "provider": "openai",
    "id": "marin"
  },
  "greeting": "Thanks for calling Demo Dental! This is Mia. How can I help you today?",
  "transfer_number": "",
  "booking_enabled": true,
  "messages_enabled": true,
  "numbers": [
    {
      "id": "7f3c1e5a-9b2d-4e6f-a8c0-1d3b5f7e9a46",
      "number": "+12125550101",
      "name": "Demo Dental",
      "receptionist_id": "d4b8f2a6-1c3e-4a5b-9d7f-8e6c4a2b0d35",
      "created_at": "2026-09-02T17:20:00.000Z"
    }
  ],
  "created_at": "2026-09-02T17:20:00.000Z",
  "updated_at": "2026-09-02T17:20:00.000Z"
}

List phone numbers

GET/v1/numbers

Scopereceptionists:read

The account's active numbers and the receptionist answering each.

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

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 numbers.
    • dataarray of PhoneNumberRequired

      This page of results.

      PhoneNumber fields
      • idstring (uuid)Required

        Number id.

      • numberstringRequired

        The number (E.164).

      • namestringRequired

        Its label.

      • receptionist_idstring (uuid) or nullRequired

        The receptionist answering it.

      • created_atstring (date-time)Required

        Added.

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

Example response (200)

{
  "data": [
    {
      "id": "7f3c1e5a-9b2d-4e6f-a8c0-1d3b5f7e9a46",
      "number": "+12125550101",
      "name": "Demo Dental",
      "receptionist_id": "d4b8f2a6-1c3e-4a5b-9d7f-8e6c4a2b0d35",
      "created_at": "2026-09-02T17:20:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

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