Primeiros passos

🔒 Autenticação

Header Authorization com o UUID do access_token (sem Bearer). Para obter o token, siga o passo a passo em Access token. GET /health não usa esse header.

🚀 Primeiros passos

1. Criar o formulário

POST /api/v1/forms

{
  "name": "Cadastro de cliente",
  "callback_url": "https://parceiro.exemplo.com/hooks/clickform"
}

Página de referência: Criar Formulário.

2. Criar uma versão (os campos)

POST /api/v1/forms/{form_key}/versions

{
  "settings": {
    "title": "Atualização de contato",
    "subtitle": "Por favor, confirme os dados de contato."
  },
  "fields": [
    { "label": "Nome completo", "type": "text", "required": true, "order": 1 },
    { "label": "Whatsapp", "type": "phone_number", "required": true, "order": 2 }
  ]
}

Página de referência: Criar Versão.

3. Criar um run (o link único de preenchimento)

POST /api/v1/versions/{version_key}/runs

{
  "context": {
    "nome-completo-59661f5fe933": { "value": "Maria da Silva", "read_only": false }
  }
}

A resposta traz form_url — o link único para o contato preencher. notification.whatsapp dispara o convite. access_verification pede uma confirmação antes de abrir o formulário. Página de referência: Criar Run.

4. Receber a resposta

Quando o preenchimento termina, o ClickForm pode avisar a sua aplicação. A configuração do webhook está em Webhook do ClickForm.

Também é possível consultar GET /api/v1/versions/{version_key}/runs/{run_key} (campo responses).

5. Ambientes

O sandbox está liberado para testes. Produção exige o Módulo de Coleta de Dados (ClickForm) contratado. Para saber mais sobre os ambientes, acesse este tutorial. Abaixo, as URLs a serem utilizadas:

✅ Checklist de sucesso

• Guardei o form_key e o version_key retornados?
• O context do run usa as mesmas key dos campos da versão?
• Configurei callback_url para não depender de polling?

Próximo passo ➡️

• Criar e utilizar formulários — todos os tipos de campo, condições e verificação de acesso.
• Webhook — receba o aviso quando o preenchimento terminar.
• Collections — Postman, Insomnia e Bruno prontos para testar o Módulo de Coleta de Dados (ClickForm).
• FAQ: dúvidas em ClickFlow — respostas curtas para as dúvidas mais comuns.