Receber leads do seu site
Acesso: leads:write para registrar e leads:read para ler a conversão.
Quando uma pessoa pede contato (formulário do seu site, landing, app, chat
próprio), mande a conversão para POST /v1/inbound-submissions. Ela segue o
mesmo caminho de um formulário do Preflow:
- vira MQL e a conta vai para Qualificadas;
- as respostas ficam no lead e a origem (UTM, campanha, página) entra na atribuição e nos painéis de marketing;
- a configuração de Inbound do workspace decide a cadência, quem atende e quem
é avisado, e as regras de roteamento recebem a
campaigne outm_campaign.
curl https://api.preflow.sale/v1/inbound-submissions \ -H "Authorization: Bearer $PREFLOW_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "submission_id": "site-form-8812", "contact": { "name": "Ana Souza", "email": "ana@empresa.com.br", "phone": "+5511999998888", "company": "Empresa" }, "answers": [ { "key": "tamanho_time", "label": "Quantas pessoas no time comercial?", "value": "11-50" } ], "campaign": "black-friday-2026", "attribution": { "utm_source": "google", "utm_medium": "cpc", "utm_campaign": "black-friday-2026", "landing_url": "https://empresa.com.br/contato" }, "consent": { "granted": true, "text": "Aceito receber contato da Empresa." } }'{ "id": "6e0b…", "object": "inbound_submission", "submission_id": "site-form-8812", "status": "completed", "result": "lead_created", "lead_id": "9b2c…", "contact_id": null, "qualified": true, "mql_applied": true, "matched_by": null, "inbound_cadence": { "started": true, "reason": "distribution", "cadence_id": "4f1e…" }, "form_id": null, "occurred_at": "2026-11-18T13:05:00.000Z", "created_at": "2026-11-18T13:05:01.204Z", "completed_at": "2026-11-18T13:05:02.118Z"}O que acontece em cada caso
Seção intitulada “O que acontece em cada caso”result |
Quando | O que o Preflow faz |
|---|---|---|
lead_created (201) |
Ninguém com esse e-mail, telefone ou LinkedIn | Cria o lead inbound, MQL, e começa a cadência de Inbound |
lead_updated |
O lead já existia e não está em atendimento | Preenche os dados que faltavam, grava o MQL e começa a cadência |
lead_unchanged |
O lead está perdido, ganho, arquivado, já em cadência ou foi qualificado por uma pessoa | Só registra a conversão no histórico e na atribuição; nada é reaberto |
contact_only |
"qualified": false, ou o formulário de form_id não deu MQL |
Guarda só como contato, sem lead, dono ou cadência |
- MQL por padrão. Toda conversão é MQL de marketing, como um formulário com
perguntas. Mande
"qualified": falsepara quem ainda não deve ser abordado. - Usar as regras de um formulário do Preflow. Com
form_id(de um formulário publicado em Marketing), as respostas usam os ids dos campos dele, as regras de MQL dele decidem e o funil e a campanha dele valem. funnel_idescolhe o funil do lead;campaigné o slug de uma campanha do Preflow.submission_idé o id da conversão no seu sistema. Mandar o mesmosubmission_idde novo devolve a mesma conversão (200), com qualquerIdempotency-Key. Se a resposta for202(resultado incerto), repita com o mesmosubmission_id: a conversão é retomada sem duplicar.occurred_até quando a pessoa converteu (até 30 dias atrás). Uma conversão antiga não passa por cima do que uma pessoa decidiu depois dela.attribution.fbc/fbp/fbclid: com a Meta conectada, a conversão também vai para a API de Conversões da Meta.- A chave do formulário pode ter só
leads:write: a resposta não traz os dados do lead nemmatched_by. Comleads:read, vem tambémlead. - Limite próprio: 120 conversões por minuto por chave. As respostas somam até
64 KB, e texto com caractere de controle (fora tab e quebra de linha) é
recusado com
400. - Contato que pediu para não ser contatado (supressão global, da agência ou do
workspace) é recusado com
422 lead_suppressedantes de qualquer registro. - Ao terminar, sai o webhook
inbound.submission_received(veja Eventos).
API de conversão ou POST /v1/leads?
Seção intitulada “API de conversão ou POST /v1/leads?”| Use | Quando |
|---|---|
POST /v1/inbound-submissions |
Uma pessoa pediu contato agora (formulário, landing, app). Conta como entrada do lead, vira MQL e entra na atribuição |
POST /v1/leads |
Seu sistema tem um cadastro para levar ao Preflow (ERP, CRM, importação). O lead entra sem MQL e o que já existe não muda |
Do formulário do seu site até a API
Seção intitulada “Do formulário do seu site até a API”A chave é secreta: o formulário do site manda os dados para o seu servidor, e o servidor chama o Preflow. Exemplo em Node (Express):
app.post('/contato', express.json(), async (req, res) => { const response = await fetch('https://api.preflow.sale/v1/inbound-submissions', { method: 'POST', headers: { Authorization: `Bearer ${process.env.PREFLOW_API_KEY}`, 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ submission_id: req.body.form_submission_id, contact: { name: req.body.name, email: req.body.email, phone: req.body.phone }, answers: [{ key: 'mensagem', label: 'Mensagem', value: req.body.message }], attribution: { utm_source: req.body.utm_source, utm_campaign: req.body.utm_campaign, landing_url: req.get('referer') }, }), }); res.status(response.ok ? 200 : 502).end();});Mande utm_* só quando houver valor: campo vazio é ignorado, campo
desconhecido é recusado (400).