Símbolo da AmivuSímbolo da AmivuDevelopers

Formulários

Ler os formulários e as respostas, e responder pela API como quem abre o link.

O plugin Formulários junta dados do cliente direto no CRM: cada pergunta pode gravar num dado do contato ou num campo personalizado, e a resposta pode pôr etiqueta, mandar o card para uma etapa do quadro e passar a conversa a um time. A pessoa responde pelo link público, pelo link pessoal que a equipe manda na conversa, pela Ami ou pela equipe no painel. Pela API você lê os formulários e as respostas, e envia respostas como quem responde pelo link.

Precisa do plugin instalado
Sem o plugin Formulários na conta, toda rota de /v1/forms volta 403 plugin_not_installed. Os alcances são forms:read e forms:write, à parte de contacts:write: enviar resposta grava no contato.

O formulário e as perguntas

GET /v1/forms lista os publicados e os encerrados, dos mais novos para os mais antigos. Rascunho nunca aparece: o que a API mostra é sempre a versão publicada, com o número dela em version.

Terminal
curl https://api.amivu.com.br/v1/forms/frm_01K7ZFA5X8Q2M4N6P8R0T2V4W6 \
  -H "Authorization: Bearer $AMIVU_API_KEY"
Resposta
{
  "object": "form",
  "id": "frm_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
  "name": "Matrícula",
  "status": "published",
  "url": "https://amivu.com.br/f/k3m9q2xw",
  "version": 3,
  "questions": [
    { "key": "nome", "type": "short_text", "label": "Seu nome", "required": true, "conditional": false, "options": [] },
    { "key": "telefone", "type": "phone", "label": "WhatsApp", "required": true, "conditional": false, "options": [] },
    {
      "key": "curso",
      "type": "single_select",
      "label": "Curso",
      "required": true,
      "conditional": false,
      "options": [
        { "id": "o4k2j9x1a", "label": "Inglês" },
        { "id": "o7m3p0q2b", "label": "Espanhol" }
      ]
    }
  ],
  "published_at": "2026-11-17T14:02:11.000Z",
  "created_at": "2026-11-10T09:30:00.000Z"
}
  • key é o nome da pergunta em answers, no CSV das respostas e na variável da mensagem. Ela não muda entre versões, então é o que a sua integração guarda.
  • url é o endereço público; vem null no formulário encerrado e no que só se responde pelo link pessoal, pela Ami ou pela equipe.
  • conditional marca a pergunta que só aparece conforme outra resposta. Ela só conta (e só é obrigatória) quando a condição vale.

Ler as respostas

GET /v1/forms/{form_id}/responses lista as respostas, das mais novas para as mais antigas, e filtra por contact_id, submitted_after e submitted_before. Cada resposta traz as respostas pela key das perguntas da versão que a pessoa respondeu, e não da atual.

Terminal
curl "https://api.amivu.com.br/v1/forms/frm_01K7ZFA5X8Q2M4N6P8R0T2V4W6/responses?submitted_after=2026-11-01T00:00:00Z" \
  -H "Authorization: Bearer $AMIVU_API_KEY"
Uma resposta
{
  "object": "form_response",
  "id": "frr_01K7ZG2B4C6D8E0F2G4H6J8K0M",
  "form_id": "frm_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
  "form_version": 3,
  "contact_id": "cnt_01K7ZFB3N5P7Q9R1S3T5V7W9X1",
  "conversation_id": null,
  "source": "public",
  "answers": {
    "nome": "Marina Souza",
    "telefone": "5515999990000",
    "curso": { "options": ["Inglês"], "other": null }
  },
  "utm": { "source": "instagram", "medium": "bio", "campaign": "matriculas", "term": null, "content": null },
  "page_url": "https://escola.com.br/matricula",
  "submitted_at": "2026-11-17T15:20:41.000Z"
}

source diz por onde veio: public (o link público), embed (o formulário no site), link (o link pessoal), team, ami ou api. A resposta sem telefone, sem e-mail e sem contato escolhido fica anônima, com contact_id: null.

Enviar uma resposta

POST /v1/forms/{form_id}/responses responde como quem abre o link: as respostas são conferidas contra a versão publicada, o contato é achado (ou criado) pelo telefone ou pelo e-mail respondidos, e as ações do formulário rodam: os campos, as etiquetas, o card no quadro e o time. Com contact_id, a resposta vai para esse contato; com conversation_id, fica ligada à conversa, que precisa ser dele.

Terminal
curl https://api.amivu.com.br/v1/forms/frm_01K7ZFA5X8Q2M4N6P8R0T2V4W6/responses \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: matricula-8841" \
  -d '{
    "answers": {
      "nome": "Marina Souza",
      "telefone": "+55 15 99999-0000",
      "curso": "o4k2j9x1a"
    }
  }'

Volta 201 com a resposta gravada, no formato da leitura. A resposta inválida volta 422 validation_error com a pergunta em param (answers.telefone) e a mesma frase que a pessoa veria no formulário. O formulário encerrado volta 409 form_closed.

A resposta roda as ações de verdade
Com a chave de produção, ela grava no contato, põe etiqueta, move o card e dispara as automações por formulário, como uma resposta pelo link. Use o Idempotency-Key para uma nova tentativa não responder duas vezes.

O formato de cada resposta

typeNo envioNa leitura
short_text, long_text, email, phone, tax_idtextotexto (o telefone só com dígitos, o e-mail em minúsculas)
number, scalenúmeronúmero
currencycentavos, inteiro (1290 é R$ 12,90)centavos
date"AAAA-MM-DD"o mesmo texto
date_time"AAAA-MM-DDTHH:mm", no fuso da contao mesmo texto
single_select, multi_selecto id da opção, a lista de ids, ou { "options": [ids], "other": "texto" }{ "options": [rótulos], "other": texto ou null }
booleantrue ou falsetrue ou false
consenttruetrue
hiddentexto (o de valor fixo se preenche sozinho)texto
filenão se responde pela API[{ "name", "size", "mime" }]

Na escolha, o envio vai pelos ids das opções, que não mudam quando o rótulo é corrigido; a leitura devolve os rótulos, como a pessoa os viu. A pergunta que a resposta não traz fica em branco, e a obrigatória em branco é recusada.

O evento

Toda resposta, venha de onde vier, dispara o webhook form.response.submitted, com data.form_response no formato acima e data.contact (ou null, na anônima). Ver Eventos.

Sandbox

Os formulários são os mesmos nos dois ambientes. As respostas, como os contatos, seguem a chave: a de sandbox não vê as de produção, e a resposta que ela envia fica no sandbox, com o contato dela. Ver Ambientes.

O que a API não faz

  • Criar ou editar formulário. O construtor fica no painel, com a prévia e a conferência antes de publicar.
  • Responder pergunta de arquivo. O arquivo sobe pela página do formulário; a pergunta de arquivo obrigatória impede o envio pela API.
  • Apagar resposta. Fica no painel, com a permissão de gerenciar formulários.

Veja também Contatos e Automações, onde o gatilho de formulário e o bloco "Mandar formulário" entram no fluxo.

Escrevemos sobre operação de atendimento, canais e IA no blog da Amivu.