Forms define the advanced fields you can attach to contacts, such as consents, surveys, level of support, custom fields, presence status, and tasks.
| Type | Description |
|---|
consent | GDPR or custom consent checkboxes |
survey | Multi-question survey forms |
level_of_support | Political or engagement level ratings |
custom_fields | Arbitrary key-value fields |
presence_status | Attendance or presence tracking |
tasks | Action or task forms |
GET /v1/forms/type/{type} to list all forms of a given type (the canonical route).
GET /forms/{id} retrieves a single form by its numeric ID. Passing a type string to /{arg} (e.g. /forms/consent) is deprecated — use /v1/forms/type/consent instead.
When you fetch a contact, advanced fields appear as formdatas entries. This is the lower-level structure used to associate a contact with a form and a selected value:
{
"formdatas": [
{
"form_id": 12,
"form_ref_id": 45
}
]
}
form_id — the ID of the form (advanced field definition)form_ref_id — the ID of the selected value/option within that form
Use GET /forms/{id} to decode the form definition and map form_ref_id to a human-readable value.
POST /contacts and PATCH /contacts/{id} can also use formdatas to link a contact to a form and a selected value. Use GET /v1/forms/type/{type} to discover form definitions and GET /forms/{id} to decode the form and option IDs.
For write payload examples and endpoint-specific contact update guidance, see Create and update contacts. Last modified on June 16, 2026
