> ## Documentation Index
> Fetch the complete documentation index at: https://docs.animo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Forms

# Forms

## Overview

Forms are reusable field collections belonging to a company. They are used by activations, ticket types, and other features. The API supports listing, creating, and updating forms and their fields.

**Subscription:** Pro plan required. Upgrade at [https://app.animo.co/admin/settings/billing](https://app.animo.co/admin/settings/billing).

## Form field types

Field `type` values fall into two categories:

### Custom fields

General-purpose fields you can add freely to any form. Use the `type` value in the API when creating or updating fields.

| Type       | Label           | Description                                              |
| ---------- | --------------- | -------------------------------------------------------- |
| `text`     | Text            | Single-line text input. Supports `placeholder`.          |
| `textarea` | Multi-line text | Multi-line text input. Supports `placeholder`.           |
| `number`   | Number          | Numeric input. Supports `placeholder`, `min`, and `max`. |
| `date`     | Date            | Date picker.                                             |
| `time`     | Time            | Time picker.                                             |
| `url`      | URL             | URL input. Supports `placeholder`.                       |
| `file`     | File            | File upload.                                             |
| `option`   | Options         | Multiple-choice field. Requires an `options` array.      |
| `select`   | Select box      | Dropdown selection. Requires an `options` array.         |
| `toggle`   | Toggle          | On/off switch. Does not support `description`.           |
| `rating`   | Rating          | Star or scale rating input.                              |

### Common fields

Pre-defined field types that map to standard lead attributes (birthdate, phone, job title, etc.). Each common field type can appear **at most once** per form — adding a second field with the same common `type` returns a validation error.

| Type           | Label             | Description                                                                                                   |
| -------------- | ----------------- | ------------------------------------------------------------------------------------------------------------- |
| `birthdate`    | Birthdate         | Date of birth.                                                                                                |
| `company_name` | Company name      | Attendee's company name.                                                                                      |
| `company_url`  | Company URL       | Company website URL.                                                                                          |
| `consent`      | Marketing Consent | Consent checkbox. Does not support `description` (use `label` for consent text). Label max 10,000 characters. |
| `country`      | Country           | Country selection.                                                                                            |
| `gender`       | Gender            | Gender selection.                                                                                             |
| `job_title`    | Job title         | Job title or role.                                                                                            |
| `language`     | Language          | Preferred language.                                                                                           |
| `phone`        | Phone number      | Phone number input.                                                                                           |
| `social_url`   | Social URL        | Social profile URL. Supports `placeholder`.                                                                   |

### Field attributes by type

| Attribute     | Supported on                                                  |
| ------------- | ------------------------------------------------------------- |
| `description` | All types except `consent` and `toggle`                       |
| `placeholder` | `text`, `textarea`, `number`, `url`, `social_url`             |
| `required`    | All types                                                     |
| `min` / `max` | `number` only                                                 |
| `options`     | `option` and `select` — see [Options format](#options-format) |
| `position`    | All types (sort order, >= 0)                                  |

### Options format

For `option` and `select` fields, `options` accepts:

* A **plain string array** (recommended): `["Option A", "Option B"]`
* An array of `{label, value}` objects (also accepted)

## Endpoints

### List forms

* **Method:** `GET`
* **Path:** `/api/v1/{company}/forms`
* **Scope:** `forms:read`
* **Subscription:** Pro plan (`USE_API`)

#### Path parameters

| Name      | Type   | Description  |
| --------- | ------ | ------------ |
| `company` | string | Company sqid |

#### Query parameters

| Name   | Type    | Description                           |
| ------ | ------- | ------------------------------------- |
| `q`    | string  | Filter by form name (substring match) |
| `page` | integer | Page number                           |

#### Response `200`

```json theme={null}
{
  "data": [
    {
      "id": "v7KAa",
      "name": "Registration form",
      "created_at": "2026-02-01T10:00:00.4040+00:00",
      "fields": [
        {
          "id": "ff1Ab",
          "type": "text",
          "label": "Email address",
          "description": "We'll send your ticket here",
          "position": 0,
          "placeholder": "you@example.com",
          "required": true
        }
      ]
    }
  ],
  "links": { "...": "..." },
  "meta": { "...": "..." }
}
```

Use the form `id` (sqid) as `form_id` when attaching a form to a ticket type.

#### Form field fields

| Field         | Type    | Description                                            |
| ------------- | ------- | ------------------------------------------------------ |
| `id`          | string  | Field sqid                                             |
| `type`        | string  | Field type — see [Form field types](#form-field-types) |
| `label`       | string  | Display label                                          |
| `description` | string  | Shown for types that allow descriptions                |
| `options`     | array   | Options for choice fields                              |
| `position`    | integer | Sort order                                             |
| `placeholder` | string  | Placeholder for supported types                        |
| `required`    | boolean | Whether the field is required                          |
| `min`         | number  | Min value for number fields                            |
| `max`         | number  | Max value for number fields                            |

***

### Show form

* **Method:** `GET`
* **Path:** `/api/v1/{company}/forms/{form}`
* **Scope:** `forms:read`
* **Subscription:** Pro plan (`USE_API`)

#### Response `200`

Single `FormResource` with `fields` array.

***

### Create form

* **Method:** `POST`
* **Path:** `/api/v1/{company}/forms/create`
* **Scope:** `forms:create`
* **Subscription:** Pro plan (`USE_API`)

#### Request body

See the request body table below for top-level field requirements. Individual form fields are validated when included in the `fields` array.

```json theme={null}
{
  "name": "Registration form",
  "fields": [
    {
      "type": "text",
      "label": "Email address",
      "description": "We'll send your ticket here",
      "placeholder": "you@example.com",
      "required": true,
      "position": 0
    },
    {
      "type": "company_name",
      "label": "Company",
      "position": 1
    }
  ]
}
```

| Field                  | Required                        | Description                                                                      |
| ---------------------- | ------------------------------- | -------------------------------------------------------------------------------- |
| `name`                 | Yes                             | Form name                                                                        |
| `fields`               | Yes                             | Array of field objects                                                           |
| `fields[].type`        | Yes                             | Field type — see [Form field types](#form-field-types)                           |
| `fields[].label`       | Yes                             | Display label                                                                    |
| `fields[].description` | No                              | Field help text (not all types support it)                                       |
| `fields[].placeholder` | No                              | Input placeholder                                                                |
| `fields[].required`    | No                              | Mark field as required                                                           |
| `fields[].position`    | No                              | Sort order (>= 0)                                                                |
| `fields[].options`     | If type is `option` or `select` | String array or `{label, value}` objects — see [Options format](#options-format) |
| `fields[].min`         | No                              | Min for number fields                                                            |
| `fields[].max`         | No                              | Max for number fields                                                            |

#### Response `201`

Returns the created `FormResource`.

***

### Update form

* **Method:** `PATCH`
* **Path:** `/api/v1/{company}/forms/{form}`
* **Scope:** `forms:update`
* **Subscription:** Pro plan (`USE_API`)

#### Request body

```json theme={null}
{
  "name": "Updated form name",
  "fields": [
    {
      "id": "ff1Ab",
      "label": "Updated label"
    },
    {
      "type": "text",
      "label": "New field",
      "position": 2
    }
  ]
}
```

* Include `id` on a field to update an existing field.
* Omit `id` to create a new field on the form.
* Only `name` can be changed at the form level.

#### Response `200`

Returns the updated `FormResource`.

## Not implemented

* `DELETE /api/v1/{company}/forms/{form}` — no route exists (`forms:delete` scope is registered but unused). Forms created via the API cannot be deleted through the API.

## Related

* [Authentication](../authentication.md)
* [Conventions](../conventions.md)
* [Activations](activations.md)
* [Webhooks](webhooks.md) — `submissions:subscribe` scope