Formulários

Base path: /api/v1/forms Scopes: forms:read | forms:submissions:read

Formulários são templates de captura de lead que o CRM gera (embed em sites/landing pages). Cada submission cria/atualiza um contato automaticamente.

A API expõe leitura dos formulários e de suas submissions. Criação e edição de formulários (estrutura de campos, design, redirects) só pela UI — é decisão de marketing/admin, não fluxo programático.

Lista formulários

GET /api/v1/forms

Scope: forms:read

curl https://app.indutivacrm.com.br/api/v1/forms \
  -H "X-API-Key: crm_live_..."

[
  {
    "id": "ckl4f01...",
    "name": "Newsletter — landing page",
    "slug": "newsletter-lp",
    "embedUrl": "https://app.indutivacrm.com.br/forms/newsletter-lp",
    "fields": [
      { "name": "email", "label": "E-mail", "type": "email", "required": true },
      { "name": "firstName", "label": "Nome", "type": "text", "required": true }
    ],
    "submissionsCount": 1234,
    "createdAt": "2026-01-15T00:00:00.000Z"
  }
]

Busca um formulário

GET /api/v1/forms/:id

Scope: forms:read

Retorna o form com a estrutura completa de campos (incluindo opções de select, validações, etc.) — útil pra integrações que querem mostrar o mesmo form em outro lugar.

Lista submissions

GET /api/v1/forms/:id/submissions?page=1&limit=50

Scope: forms:submissions:read

Param	Tipo	Default
`page`	number	1
`limit`	number	50 (máx 100)

{
  "data": [
    {
      "id": "ckl4s01...",
      "formId": "ckl4f01...",
      "contactId": "ckl4z01...",
      "values": {
        "email": "maria@empresa.com.br",
        "firstName": "Maria"
      },
      "metadata": {
        "ipAddress": "200.123.45.67",
        "userAgent": "Mozilla/5.0...",
        "referrer": "https://acme.com.br/landing"
      },
      "createdAt": "2026-05-22T14:30:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 50, "total": 1234, "totalPages": 25 }
}

Erros específicos

Status	`error`	Cenário
403	`insufficient_scope`	Tentou `/submissions` sem `forms:submissions:read`
404	`not_found`	Form não existe