Skip to content
Chatvia Docs
On this page

API reference

Forms and leads

Get in touch: Ahmad Mayahi, creator of Chatvia, Spectra and Shakomako

These endpoints manage an agent's inline forms and read what visitors sent through them. An inline form is a small form the agent shows inside the chat, for example to collect a name and email, or to book a call. Each form a visitor sends is a submission, also called a lead. Leads explains forms for people who use the dashboard.

For example, a sales team can copy every new lead into its CRM each hour: list the submissions of the "Book a demo" form and import the new ones.

Read the overview first for the base URL, keys, errors and paging.

Needs a license key

Forms and leads need a license key on your Chatvia install, like the rest of the API. See What needs a key.

The form object

json
{
  "id": "0199f420-8f9a-7b0c-9d1e-2f3a4b5c6d7e",
  "slug": "book-a-demo",
  "name": "Book a demo",
  "subtitle": "We'll get back to you within one working day.",
  "form_type": "booking",
  "schema": [
    { "key": "name", "label": "Your name", "type": "text", "required": true },
    { "key": "email", "label": "Work email", "type": "email", "required": true },
    {
      "key": "team_size",
      "label": "Team size",
      "type": "select",
      "required": false,
      "options": [
        { "value": "1-10", "label": "1 to 10" },
        { "value": "11-50", "label": "11 to 50" }
      ]
    }
  ],
  "lead_field_map": { "name": "name", "email": "email" },
  "success_message": "Thanks! We'll be in touch.",
  "agent_instructions": "Offer this form when someone asks for a demo or pricing for a team.",
  "is_active": true,
  "submissions_count": 12,
  "created_at": "2026-10-10T14:00:00+00:00"
}
Field Type Meaning
id string The form's id.
slug string A short name made from the form's name when it was created. It never changes.
name string The title shown above the form.
subtitle string or null A line shown under the title.
form_type string lead, booking, qualification or generic.
schema array The fields, in order. See below.
lead_field_map object or null Which field holds which standard lead detail. Keys are field keys, values are name, email, phone, job_title, company, location or message.
success_message string or null Shown to the visitor after they send the form.
agent_instructions string or null Tells the agent when to offer the form.
is_active boolean Whether the agent may show the form.
submissions_count integer How many visitors sent the form.
created_at string When the form was created.

Each field in schema has:

Field key Type Required Notes
key string yes Starts with a letter, then letters, digits and underscores. Up to 64 characters. Submissions use it as the name of the answer.
label string yes Up to 120 characters.
type string yes text, email, tel, number, textarea, select, radio, checkbox, multicheckbox or date.
required boolean no Whether the visitor must fill it in.
placeholder string no Up to 120 characters.
options array no For choice fields. Each option has a value and a label, up to 120 characters each.

List forms

Returns the agent's forms, newest first.

text
GET /api/v1/agents/{agent}/forms

Who can call it: anyone with access to the agent.

bash
curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/forms \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is { "data": [form, …], "next_cursor": … }. See Pagination.

Create a form

Creates a form and turns on the agent's Forms capability, so the agent can start offering it.

text
POST /api/v1/agents/{agent}/forms

Who can call it: the owner, or a teammate with Manage Connectors.

Body field Type Required Default Notes
name string yes Up to 120 characters.
form_type string yes lead, booking, qualification or generic.
schema array yes 1 to 30 fields. See above.
subtitle string no none Up to 300 characters.
success_message string no none Up to 500 characters.
agent_instructions string no none Up to 500 characters.
is_active boolean no true
lead_field_map object no none See above.
bash
curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/forms \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Book a demo",
    "form_type": "booking",
    "schema": [
      { "key": "name", "label": "Your name", "type": "text", "required": true },
      { "key": "email", "label": "Work email", "type": "email", "required": true }
    ],
    "lead_field_map": { "name": "name", "email": "email" },
    "agent_instructions": "Offer this form when someone asks for a demo."
  }'

The answer is 201 Created with { "data": form }.

Get a form

text
GET /api/v1/agents/{agent}/forms/{form}

Who can call it: anyone with access to the agent.

bash
curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/forms/0199f420-8f9a-7b0c-9d1e-2f3a4b5c6d7e \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is { "data": form }.

Update a form

Changes the fields you send. A field you leave out keeps its value. When you send schema, it replaces the whole field list. lead_field_map: null clears the map. The slug never changes.

text
PATCH /api/v1/agents/{agent}/forms/{form}

Who can call it: the owner, or a teammate with Manage Connectors.

bash
curl -X PATCH https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/forms/0199f420-8f9a-7b0c-9d1e-2f3a4b5c6d7e \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

The answer is { "data": form }.

Delete a form

Deletes the form and all its submissions. When it was the agent's last form, the agent's Forms capability turns off.

text
DELETE /api/v1/agents/{agent}/forms/{form}

Who can call it: the owner, or a teammate with Manage Connectors.

bash
curl -X DELETE https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/forms/0199f420-8f9a-7b0c-9d1e-2f3a4b5c6d7e \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is 204 No Content. Export the submissions first if you want to keep them.

List submissions

Returns the submissions of one form, newest first. Forms the agent showed but the visitor never sent are left out.

text
GET /api/v1/agents/{agent}/forms/{form}/submissions

Who can call it: the owner, or a teammate with View leads.

bash
curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/forms/0199f420-8f9a-7b0c-9d1e-2f3a4b5c6d7e/submissions \
  -H "Authorization: Bearer $CHATVIA_API_KEY"
json
{
  "data": [
    {
      "id": "0199f425-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
      "values": { "name": "Ana Silva", "email": "[email protected]", "team_size": "11-50" },
      "submitted_at": "2026-10-24T16:45:12+00:00",
      "conversation_id": "0199f3f1-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
      "created_at": "2026-10-24T16:44:30+00:00"
    }
  ],
  "next_cursor": null
}
Field Meaning
id The submission's id.
values The visitor's answers, named by the field keys. They can hold personal data, so store them with care.
submitted_at When the visitor sent the form.
conversation_id The conversation the form was sent in, when there is one. Read it with Get a conversation.
created_at When the agent first showed the form.

Export submissions as CSV

Downloads the submissions of one form as a CSV file, a plain spreadsheet file. It has one column per form field and one for when it was sent.

text
GET /api/v1/agents/{agent}/forms/{form}/submissions/export

Who can call it: the owner, or a teammate with Export leads. This endpoint has its own rate limit of 10 a minute.

Query parameter Type Required Notes
ids[] array of strings no Only export these submissions, up to 1,000. Leave it out to export every sent submission.
bash
curl "https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/forms/0199f420-8f9a-7b0c-9d1e-2f3a4b5c6d7e/submissions/export" \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -o submissions.csv

The answer is the file itself, with the type text/csv, not JSON. The file is named like submissions-book-a-demo-20261025-120000.csv. Values that a spreadsheet app could run as a formula are made safe first.

Search guides, settings and commands.