Criar e utilizar formulários

📐 Estrutura de uma Version

Uma versão (Version) tem settings (textos de UI) e fields[] (o schema).

settings: title, subtitle, finish_title, finish_subtitle, finish_info, e steps (mapa índice → rótulo, para formulários em múltiplas etapas).

Cada field tem label, type, required, order, step (índice da etapa), placeholder, help_balloon (texto de ajuda) e options (estrutura específica de cada tipo).

🧱 Tipos de campo

`type`	Descrição	`options` relevantes
`text`	Texto curto	`maxlength`
`textarea`	Texto longo	`maxlength`
`number`	Numérico	—
`number_range`	Numérico com faixa	`min_value`, `max_value`, `decimal_places`, `min_error_message`, `max_error_message` (aceitam os placeholders `{min_value}`/`{max_value}`/`{decimal_places}`)
`email`	E-mail	—
`phone_number`	Telefone/WhatsApp	—
`date`	Data	—
`cpf` / `cnpj`	Documento	—
`currency`	Monetário	—
`cep`	CEP, com sub-campos de endereço	`fields[]` (`attribute_type`: `street`, `state`, `city`, `neighborhood`, `number`, `complement`)
`image` / `file`	Upload	—
`header` / `paragraph`	Texto estático (sem valor de resposta)	—
`select`	Lista suspensa (única escolha)	`values[]`
`radio-group`	Única resposta em botões	`other` (permite "outro"), `values[]` (cada item aceita `selected: true` para pré-marcar uma opção como resposta default)
`checkbox-group`	Múltiplas respostas	`other`, `values[]`
`repeater`	Bloco repetível (ex.: dependentes)	`button_label`, `fields[]` (sub-campos)

🔀 Regras condicionais (`conditions`)

Um campo pode declarar conditions[] — regras forward-chaining que mostram/escondem outros campos com base na própria resposta:

{
  "label": "Plano",
  "type": "select",
  "options": {
    "values": [
      { "label": "Full", "value": "FULL" },
      { "label": "Basic", "value": "BASIC" }
    ]
  },
  "conditions": [
    { "action": "show", "operator": "equal", "value": "FULL", "fields": ["Detalhes do plano"] }
  ]
}

🔑 Pré-preenchimento e injeção de contexto (Run)

Ao criar um Run, o context mapeia a key de cada campo para um valor — read_only: true bloqueia a edição pelo contato:

{
  "context": {
    "cpf": { "value": "529.982.247-25", "read_only": true },
    "nome": { "value": "Maria", "read_only": false }
  },
  "expires_at": "2026-12-31T23:59:59Z"
}

Verificação de acesso opcional (`access_verification`)

Antes de liberar o preenchimento, você pode exigir que o contato confirme um dado (ex.: CPF), com máscara parcial:

{
  "context": {
    "cpf": { "value": "588.843.362-44", "read_only": true }
  },
  "access_verification": {
    "label": "Informe seu CPF para prosseguir",
    "expected_value": "588.843.362-44",
    "mask_percentage": 90
  }
}

Quando presente, o status do run passa a access_verification_required até a validação. mask_percentage é opcional (padrão 90).

⚠️ Regras de imutabilidade e estado

Um run com status: done não pode ser editado (PUT) nem removido (DELETE) — responde 409.
callback_url no run é opcional e específico dessa execução — soma-se (não substitui) ao callback_url do formulário, quando configurado.

📍 Endpoints

Recurso	Método	Endpoint
Forms	GET / POST	`/api/v1/forms`
Forms	GET / PUT / DELETE	`/api/v1/forms/{form_key}`
Versions	GET / POST	`/api/v1/forms/{form_key}/versions`
Versions	GET / PUT / DELETE	`/api/v1/forms/{form_key}/versions/{version_key}`
Runs	GET / POST	`/api/v1/versions/{version_key}/runs`
Runs	GET / PUT / DELETE	`/api/v1/versions/{version_key}/runs/{run_key}`

Referência completa, com Try It: ClickForm.

❓Precisa de ajuda? Entre em contato com o Suporte

💰Dúvida sobre planos e preços? Veja o comparativo

🔍Não sabe qual versão está usando? Descubra a sua versão

📚Respostas rápidas? Visite nosso FAQ