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
campaignandutm_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": "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"}What happens in each case
Section titled “What happens in each case”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": falsefor 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_idpicks the lead’s funnel;campaignis the slug of a Preflow campaign.submission_idis the conversion’s id in your system. Sending the samesubmission_idagain returns the same conversion (200), with anyIdempotency-Key. If the response is202(uncertain outcome), repeat with the samesubmission_id: the conversion resumes without duplicating.occurred_atis 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 nomatched_by. Withleads:read, it also includeslead. - 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_suppressedbefore anything is recorded. - When it finishes, the
inbound.submission_receivedwebhook is sent (see Events).
Conversion API or POST /v1/leads?
Section titled “Conversion API or POST /v1/leads?”| 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 |
From your website form to the API
Section titled “From your website form to the API”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).