Pular para o conteúdo

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 campaign e o utm_campaign.
Janela do terminal
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"
}
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": false para 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_id escolhe o funil do lead; campaign é o slug de uma campanha do Preflow.
  • submission_id é o id da conversão no seu sistema. Mandar o mesmo submission_id de novo devolve a mesma conversão (200), com qualquer Idempotency-Key. Se a resposta for 202 (resultado incerto), repita com o mesmo submission_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 nem matched_by. Com leads:read, vem também lead.
  • 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_suppressed antes de qualquer registro.
  • Ao terminar, sai o webhook inbound.submission_received (veja Eventos).
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

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).