Leads, accounts and cadences
A guide to the public API’s CRM routes. General conventions are in Authentication, Idempotency, Pagination and Errors.
| Route | Scope | What it’s for |
|---|---|---|
POST /v1/inbound-submissions |
leads:write |
A person asked to be contacted on your website, app or system (guide) |
GET /v1/inbound-submissions/{id} |
leads:read |
Retrieve a conversion |
POST /v1/leads |
leads:write |
Send a new lead from your system |
GET /v1/leads, GET /v1/leads/{id} |
leads:read |
Look up by email, phone or external_id, or sync |
GET /v1/leads/{id}/activities |
leads:read |
The lead’s timeline |
GET /v1/accounts, GET /v1/accounts/{id} |
accounts:read |
Stage per funnel, owners, qualification, Customer/Churn |
GET /v1/funnels |
accounts:read |
Funnels and stages |
GET /v1/cadences |
cadences:read |
Cadences that can take leads |
POST /v1/leads/{id}/cadence-enrollments |
cadences:write |
Enroll the lead in a cadence |
POST /v1/leads/{id}/cadence-stop |
cadences:write |
Stop the lead’s cadence |
GET /v1/meetings, GET /v1/meetings/{id} |
meetings:read |
Booked meetings |
Create a lead
Section titled “Create a lead”The lead comes in as inbound: the workspace’s Inbound settings decide the cadence, who handles it and who gets notified, just like a website form.
curl https://api.preflow.sale/v1/leads \ -H "Authorization: Bearer $PREFLOW_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"name":"Ana Souza","phone":"+5511999998888","email":"ana@empresa.com.br","company":"Acme","external_id":"erp-12345"}'{ "lead_id": "9b2c…", "lead": { "id": "9b2c…", "object": "lead", "name": "Ana Souza", "status": "new", "origin": "inbound", "external_ids": ["erp-12345"], "…": "…" }, "created": true, "matched_by": null, "inbound_cadence": { "started": true, "reason": "distribution", "cadence_id": "4f1e…" }}- Provide
emailorphone(E.164,+5511999998888). Phone-only leads are accepted. - Does the lead already exist? If the email or phone already belongs to a lead
in the workspace, the response is
200withcreated: falseand that lead, unchanged. A lead that is already being worked (in a cadence, lost, won or that came in through prospecting) is never reopened, andinbound_cadenceisnull. - The lead snapshot (
lead) is only returned to keys that also haveleads:read. A write-only key (a form, for example) gets onlylead_id. - Its own limit: 60 leads per minute per key.
external_idis the lead’s id in your system, unique within the workspace. Sending the sameexternal_idagain returns the same lead, unchanged (matched_by: "external_id"). Two simultaneous requests with the sameexternal_idnever create two leads: the second gets409 external_id_in_progressand, when retried, the lead created by the first. Look it up withGET /v1/leads?external_id=erp-12345.- A contact who asked not to be contacted responds
422 lead_suppressed. sourceis a free-form label from your system (e.g.erp), stored with the entry.
Search and sync
Section titled “Search and sync”# by email, phone or your system's idcurl "https://api.preflow.sale/v1/leads?email=ana@empresa.com.br" -H "Authorization: Bearer $PREFLOW_API_KEY"
# sync: everything that changed since last time, page by pagecurl "https://api.preflow.sale/v1/leads?updated_since=2026-11-16T00:00:00Z&limit=100" -H "Authorization: Bearer $PREFLOW_API_KEY"The list is ordered by update time (oldest first). Store the updated_at of the
last item and use it as updated_since in the next run; next_cursor takes you
to the next page of the same run. Accounts work the same way
(GET /v1/accounts?updated_since=).
To learn about changes without polling, use webhooks (see Events below).
Timeline
Section titled “Timeline”GET /v1/leads/{id}/activities returns the lead’s touches and milestones, newest
first, each with a stable public type:
| Type | What it is |
|---|---|
email.sent, email.received |
Email sent or received |
whatsapp.sent, whatsapp.received |
WhatsApp message sent or received |
call.made, call.received |
Call made or received (call.connection_status) |
linkedin.invitation_sent, linkedin.invitation_accepted, linkedin.sent, linkedin.received |
|
meeting.scheduled, meeting.confirmed, meeting.completed |
Meeting |
lead.lost, lead.reactivated, lead.status_changed |
Change in the lead’s status |
lead.received_from_api |
The lead came in through the API |
note |
Note |
actor.type says who acted: human, ai, lead, integration or system.
Internal Preflow records are not shown.
Accounts and funnels
Section titled “Accounts and funnels”The account owns the lead. GET /v1/accounts/{id} returns:
funnels: one entry per funnel, with the fixed stage (new,qualified,scheduled,completed,no_show,negotiation,won,lost) and the intermediate stage created by the workspace, if any.owners.pre_salesandowners.sales: who handles the account before and after the meeting.qualification,is_customer(Customer) andis_churn(Churn). A Churn account leaves the board (on_board: falsein every funnel); a Customer account only stays in Sales.
GET /v1/funnels lists the funnels, the fixed stages with the name shown in
Preflow and each stage’s intermediate stages.
Cadences
Section titled “Cadences”curl https://api.preflow.sale/v1/leads/9b2c…/cadence-enrollments \ -H "Authorization: Bearer $PREFLOW_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"cadence_id":"4f1e…"}'- Enrollment works exactly like it does on the screen, with the same refusals: the lead is already in the cadence, engagement pause, the lead has already had a meeting, lost-lead cooldown, a cadence whose steps would all be born cancelled. Each one has a code in Errors.
- The steps are carried out by the pre-sales owner of the lead’s account. On the timeline the enrollment shows up as made by the integration, with the key, and doesn’t count as a touch. The key can only enroll while the person who created it is still a workspace admin or owner.
POST /v1/leads/{id}/cadence-stopstops the cadence of this lead: other people in the same account stay in their cadences, and ongoing conversations and manually scheduled follow-ups continue. Whatever was queued for sending is cancelled; what the provider already received can’t be pulled back. With no open cadence, it respondsstopped: false.
Meetings
Section titled “Meetings”curl "https://api.preflow.sale/v1/meetings?from=2026-11-01T00:00:00Z&to=2026-12-01T00:00:00Z&status=scheduled" \ -H "Authorization: Bearer $PREFLOW_API_KEY"status:scheduled,confirmed,tentative,rescheduled,completed,no_showorcancelled.- Blocks copied from Outlook or Google calendars are not meetings and never show up.
closeris who runs the meeting;scheduled_byis who booked it.
Events
Section titled “Events”To learn about changes without polling, subscribe to the lead.*, account.* and
meeting.* events by webhook. The format of each one is in
Events.