Skip to content

Receive leads from your website

Scopes: leads:write to record and leads:read to read the conversion.

When a person asks to be contacted (a form on your website, a landing page, an app, your own chat), send the conversion to POST /v1/inbound-submissions. It follows the same path as a Preflow form:

  • it becomes an MQL and the account moves to Qualified;
  • the answers are stored on the lead and the source (UTM, campaign, page) goes into attribution and the marketing dashboards;
  • the workspace’s Inbound settings decide the cadence, who handles it and who is notified, and the routing rules receive campaign and 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": "Acme" },
"answers": [
{ "key": "team_size", "label": "How many people are on your sales team?", "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": "I agree to be contacted by Acme." }
}'
{
"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 When What Preflow does
lead_created (201) No one with that email, phone or LinkedIn Creates the inbound lead as an MQL and starts the Inbound cadence
lead_updated The lead already existed and is not being handled Fills in missing data, records the MQL and starts the cadence
lead_unchanged The lead is lost, won, archived, already in a cadence, or was qualified by a person Only records the conversion in the history and attribution; nothing is reopened
contact_only "qualified": false, or the form_id form did not produce an MQL Stores it as a contact only, with no lead, owner or cadence
  • MQL by default. Every conversion is a marketing MQL, like a form with questions. Send "qualified": false for people who should not be approached yet.
  • Use a Preflow form’s rules. With form_id (a form published in Marketing), the answers use that form’s field ids, its MQL rules decide, and its funnel and campaign apply.
  • funnel_id picks the lead’s funnel; campaign is the slug of a Preflow campaign.
  • submission_id is the conversion’s id in your system. Sending the same submission_id again returns the same conversion (200), with any Idempotency-Key. If the response is 202 (uncertain outcome), repeat with the same submission_id: the conversion resumes without duplicating.
  • occurred_at is when the person converted (up to 30 days ago). An old conversion never overrides what a person decided after it.
  • attribution.fbc / fbp / fbclid: with Meta connected, the conversion is also sent to Meta’s Conversions API.
  • The form’s key can have only leads:write: the response then has no lead data and no matched_by. With leads:read, it also includes lead.
  • Dedicated limit: 120 conversions per minute per key. Answers add up to 64 KB at most, and text with a control character (other than tab and line break) is rejected with 400.
  • A contact who asked not to be contacted (global, agency or workspace suppression) is rejected with 422 lead_suppressed before anything is recorded.
  • When it finishes, the inbound.submission_received webhook is sent (see Events).
Use When
POST /v1/inbound-submissions A person asked to be contacted just now (form, landing page, app). It counts as the lead’s entry, becomes an MQL and goes into attribution
POST /v1/leads Your system has a record to bring into Preflow (ERP, CRM, import). The lead comes in without an MQL and existing leads don’t change

The key is secret: the website form sends the data to your server, and your server calls Preflow. Example in Node (Express):

app.post('/contact', 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: 'message', label: 'Message', 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();
});

Send utm_* only when there is a value: empty fields are ignored, unknown fields are rejected (400).