Skip to content

API referenceEndpoints

Forms

Details the receptionist collects from callers, and their answers.

On this page

List intake forms

GET/v1/forms

Scopeforms:read

The details the receptionist collects from callers. Edit forms in the portal.

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 forms.
    • dataarray of FormRequired

      This page of results.

      Form fields
      • idstring (uuid)Required

        Form id.

      • namestringRequired

        Form name.

      • when_to_usestringRequired

        When the receptionist uses it.

      • receptionist_idstring (uuid) or nullRequired

        Only this receptionist uses it; null: all of them.

      • enabledbooleanRequired

        Whether it's in use.

      • fieldsarray of FormFieldRequired

        The questions.

        FormField fields
        • keystringRequired

          Stable key; answers are keyed by it.

        • labelstringRequired

          The question.

        • typestringRequired

          Kind of answer.

          One of: text, number, date, time, phone, email, choice, yes_no

        • requiredbooleanRequired

          Whether the receptionist must ask for it.

        • optionsarray of stringRequired

          Choices, for type choice.

        • helpstringRequired

          Guidance for the receptionist.

      • submissionsintegerRequired

        How many answers it has.

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

Example response (200)

{
  "data": [
    {
      "id": "f1d5b9e3-7a2c-4e4b-8d6f-0a2c4e6a8c80",
      "name": "New patient",
      "when_to_use": "a new patient wants to book",
      "receptionist_id": null,
      "enabled": true,
      "fields": [
        {
          "key": "full_name",
          "label": "Full name",
          "type": "text",
          "required": true,
          "options": [],
          "help": ""
        },
        {
          "key": "insurance",
          "label": "Insurance",
          "type": "text",
          "required": true,
          "options": [],
          "help": "Provider name, or none"
        },
        {
          "key": "how_heard",
          "label": "How did you hear about us?",
          "type": "choice",
          "required": false,
          "options": [
            "Google search",
            "Instagram",
            "A friend"
          ],
          "help": ""
        }
      ],
      "submissions": 2,
      "created_at": "2026-09-02T17:20:00.000Z",
      "updated_at": "2026-09-02T17:20:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Get a form

GET/v1/forms/{id}

Scopeforms:read

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

Path parameters

  • idstring (uuid)Required

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

      Form id.

    • namestringRequired

      Form name.

    • when_to_usestringRequired

      When the receptionist uses it.

    • receptionist_idstring (uuid) or nullRequired

      Only this receptionist uses it; null: all of them.

    • enabledbooleanRequired

      Whether it's in use.

    • fieldsarray of FormFieldRequired

      The questions.

      FormField fields
      • keystringRequired

        Stable key; answers are keyed by it.

      • labelstringRequired

        The question.

      • typestringRequired

        Kind of answer.

        One of: text, number, date, time, phone, email, choice, yes_no

      • requiredbooleanRequired

        Whether the receptionist must ask for it.

      • optionsarray of stringRequired

        Choices, for type choice.

      • helpstringRequired

        Guidance for the receptionist.

    • submissionsintegerRequired

      How many answers it has.

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

Example response (200)

{
  "id": "f1d5b9e3-7a2c-4e4b-8d6f-0a2c4e6a8c80",
  "name": "New patient",
  "when_to_use": "a new patient wants to book",
  "receptionist_id": null,
  "enabled": true,
  "fields": [
    {
      "key": "full_name",
      "label": "Full name",
      "type": "text",
      "required": true,
      "options": [],
      "help": ""
    },
    {
      "key": "insurance",
      "label": "Insurance",
      "type": "text",
      "required": true,
      "options": [],
      "help": "Provider name, or none"
    },
    {
      "key": "how_heard",
      "label": "How did you hear about us?",
      "type": "choice",
      "required": false,
      "options": [
        "Google search",
        "Instagram",
        "A friend"
      ],
      "help": ""
    }
  ],
  "submissions": 2,
  "created_at": "2026-09-02T17:20:00.000Z",
  "updated_at": "2026-09-02T17:20:00.000Z"
}

List a form's answers

GET/v1/forms/{id}/submissions

Scopeforms:read

One submission per call, newest first; answers is keyed by the form's field keys.

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

Path parameters

  • idstring (uuid)Required

    The form's id.

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 submissions.
    • dataarray of FormSubmissionRequired

      This page of results.

      FormSubmission fields
      • idstring (uuid)Required

        Submission id.

      • form_idstring (uuid)Required

        Form id.

      • call_idstring (uuid) or nullRequired

        The call it came from.

      • contact_idstring (uuid) or nullRequired

        The caller's contact.

      • caller_namestringRequired

        Caller's name.

      • caller_phonestringRequired

        Caller's number.

      • answersobjectRequired

        Answers keyed by field key.

      • notesstringRequired

        Anything else the caller said.

      • testbooleanRequired

        From the owner's own test call.

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

Example response (200)

{
  "data": [
    {
      "id": "a9e3c7f1-5d8b-4b2a-9e4c-6a8e0c2e4a91",
      "form_id": "f1d5b9e3-7a2c-4e4b-8d6f-0a2c4e6a8c80",
      "call_id": "3a7e9c15-6d2b-4f40-8e1a-5b9c7d3e1f24",
      "contact_id": "e5c9a3f7-2d4b-4c6e-8f0a-3b5d7f9c1e57",
      "caller_name": "Maria Lopez",
      "caller_phone": "+12125550147",
      "answers": {
        "full_name": "Maria Lopez",
        "insurance": "Delta Dental",
        "how_heard": "Google search"
      },
      "notes": "",
      "test": false,
      "created_at": "2026-10-25T13:32:16.000Z",
      "updated_at": "2026-10-25T13:32:16.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

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