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.
/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.
curl https://api.amivu.com.br/v1/forms/frm_01K7ZFA5X8Q2M4N6P8R0T2V4W6 \
-H "Authorization: Bearer $AMIVU_API_KEY"
{
"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 emanswers, 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; vemnullno formulário encerrado e no que só se responde pelo link pessoal, pela Ami ou pela equipe.conditionalmarca 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.
curl "https://api.amivu.com.br/v1/forms/frm_01K7ZFA5X8Q2M4N6P8R0T2V4W6/responses?submitted_after=2026-11-01T00:00:00Z" \
-H "Authorization: Bearer $AMIVU_API_KEY"
{
"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.
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.
O formato de cada resposta
| type | No envio | Na leitura |
|---|---|---|
| short_text, long_text, email, phone, tax_id | texto | texto (o telefone só com dígitos, o e-mail em minúsculas) |
| number, scale | número | número |
| currency | centavos, inteiro (1290 é R$ 12,90) | centavos |
| date | "AAAA-MM-DD" | o mesmo texto |
| date_time | "AAAA-MM-DDTHH:mm", no fuso da conta | o mesmo texto |
| single_select, multi_select | o id da opção, a lista de ids, ou { "options": [ids], "other": "texto" } | { "options": [rótulos], "other": texto ou null } |
| boolean | true ou false | true ou false |
| consent | true | true |
| hidden | texto (o de valor fixo se preenche sozinho) | texto |
| file | nã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.