Skip to main content

​
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.

​
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.
TypeLabelDescription
textTextSingle-line text input. Supports placeholder.
textareaMulti-line textMulti-line text input. Supports placeholder.
numberNumberNumeric input. Supports placeholder, min, and max.
dateDateDate picker.
timeTimeTime picker.
urlURLURL input. Supports placeholder.
fileFileFile upload.
optionOptionsMultiple-choice field. Requires an options array.
selectSelect boxDropdown selection. Requires an options array.
toggleToggleOn/off switch. Does not support description.
ratingRatingStar 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.
TypeLabelDescription
birthdateBirthdateDate of birth.
company_nameCompany nameAttendee’s company name.
company_urlCompany URLCompany website URL.
consentMarketing ConsentConsent checkbox. Does not support description (use label for consent text). Label max 10,000 characters.
countryCountryCountry selection.
genderGenderGender selection.
job_titleJob titleJob title or role.
languageLanguagePreferred language.
phonePhone numberPhone number input.
social_urlSocial URLSocial profile URL. Supports placeholder.

​
Field attributes by type

AttributeSupported on
descriptionAll types except consent and toggle
placeholdertext, textarea, number, url, social_url
requiredAll types
min / maxnumber only
optionsoption and select — see Options format
positionAll 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

NameTypeDescription
companystringCompany sqid

​
Query parameters

NameTypeDescription
qstringFilter by form name (substring match)
pageintegerPage number

​
Response 200

{
  "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": "[email protected]",
          "required": true
        }
      ]
    }
  ],
  "links": { "...": "..." },
  "meta": { "...": "..." }
}
Use the form id (sqid) as form_id when attaching a form to a ticket type.

​
Form field fields

FieldTypeDescription
idstringField sqid
typestringField type — see Form field types
labelstringDisplay label
descriptionstringShown for types that allow descriptions
optionsarrayOptions for choice fields
positionintegerSort order
placeholderstringPlaceholder for supported types
requiredbooleanWhether the field is required
minnumberMin value for number fields
maxnumberMax 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. 
{
  "name": "Registration form",
  "fields": [
    {
      "type": "text",
      "label": "Email address",
      "description": "We'll send your ticket here",
      "placeholder": "[email protected]",
      "required": true,
      "position": 0
    },
    {
      "type": "company_name",
      "label": "Company",
      "position": 1
    }
  ]
}
FieldRequiredDescription
nameYesForm name
fieldsYesArray of field objects
fields[].typeYesField type — see Form field types
fields[].labelYesDisplay label
fields[].descriptionNoField help text (not all types support it)
fields[].placeholderNoInput placeholder
fields[].requiredNoMark field as required
fields[].positionNoSort order (>= 0)
fields[].optionsIf type is option or selectString array or {label, value} objects — see Options format
fields[].minNoMin for number fields
fields[].maxNoMax 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

{
  "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.