Schema, tipos de campo e regras da Version

📐 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, key, required, order, step (índice da etapa), placeholder, help_balloon (texto de ajuda), options (estrutura específica de cada tipo) e, se quiser, external_key.

key é o identificador do campo gerado pela API a partir do rótulo, com um sufixo (nome-completo-821962496a9d). Ela vale na tela, no context do Run, na resposta gravada e no GET do Run. Pode ser omitida na criação: a API gera. Uma Version nova pode gerar outra key para a mesma pergunta.

external_key é o nome que você escolhe. No webhook de conclusão, responses e attachments usam esse nome, normalizado para snake_case. O ERP continua lendo customer_full_name mesmo quando a key gerada muda. Sem external_key, o webhook usa a key. O atributo vai na Version: uma Version nova precisa recebê-lo de novo. O detalhe está em Webhook.

🧱 Tipos de campo

Em number_range, min_value e max_value são opcionais. Se os dois vierem, o mínimo não pode ser maior que o máximo. decimal_places, quando informado, é um inteiro a partir de zero.

Data por extenso

Em campos date, use options.output_formatter: "long" para receber a resposta por extenso em português no payload enviado ao callback_url (por exemplo, "20/07/2026" → "20 de julho de 2026"). O valor persistido no Run continua no formato curto. Omitir a opção preserva o comportamento padrão.

{
  "label": "Data de nascimento",
  "type": "date",
  "required": true,
  "order": 1,
  "options": {
    "output_formatter": "long"
  }
}

🔀 Regras condicionais (conditions)

Um campo select ou radio-group pode declarar conditions[]. A API recusa conditions nos outros tipos, inclusive checkbox-group e subcampo de repeater. action é show ou hide. operator usa equal ou not_equal.

{
  "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",
  "notification": { "whatsapp": "(11) 91234-5678" }
}

notification.whatsapp é opcional e dispara o convite no WhatsApp. expires_at é gravado no Run; hoje a API não bloqueia o preenchimento depois dessa data.

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 estado

• PUT na mesma version_key substitui fields, settings e is_active. Quem ainda não enviou o formulário usa o schema vigente no momento do envio. Um Run done permanece com a resposta gravada.
• Um run com status: done não aceita PUT nem DELETE — responde 409.
• callback_url no run é opcional e específico dessa execução. Convive com o callback_url do formulário. Se as duas URLs forem iguais, ignorando espaços nas pontas, a API envia um único POST. O webhook está em Webhook do ClickForm.
• No PUT do Run, callback_url omitido mantém o valor atual. String vazia remove o callback dessa execução. access_verification omitido também mantém o valor atual. Incluir esse objeto num Run que não tinha gate muda o status para access_verification_required.

📍 Endpoints

Referência completa, com Try It!: Módulo de Coleta de Dados (ClickForm).

Próximo passo ➡️

• Webhook — receba o aviso quando o preenchimento terminar.
• Collections — teste Forms, Versions e Runs em Postman, Insomnia ou Bruno.
• Recipe: criar formulário, versão e run — acompanhe uma integração ponta a ponta.
• FAQ: dúvidas em ClickFlow — respostas curtas para as dúvidas mais comuns.