Skip to content

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

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.

Janela do terminal
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 email or phone (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 200 with created: false and that lead, unchanged. A lead that is already being worked (in a cadence, lost, won or that came in through prospecting) is never reopened, and inbound_cadence is null.
  • The lead snapshot (lead) is only returned to keys that also have leads:read. A write-only key (a form, for example) gets only lead_id.
  • Its own limit: 60 leads per minute per key.
  • external_id is the lead’s id in your system, unique within the workspace. Sending the same external_id again returns the same lead, unchanged (matched_by: "external_id"). Two simultaneous requests with the same external_id never create two leads: the second gets 409 external_id_in_progress and, when retried, the lead created by the first. Look it up with GET /v1/leads?external_id=erp-12345.
  • A contact who asked not to be contacted responds 422 lead_suppressed.
  • source is a free-form label from your system (e.g. erp), stored with the entry.
Janela do terminal
# by email, phone or your system's id
curl "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 page
curl "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).

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

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_sales and owners.sales: who handles the account before and after the meeting.
  • qualification, is_customer (Customer) and is_churn (Churn). A Churn account leaves the board (on_board: false in 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.

Janela do terminal
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-stop stops 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 responds stopped: false.
Janela do terminal
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_show or cancelled.
  • Blocks copied from Outlook or Google calendars are not meetings and never show up.
  • closer is who runs the meeting; scheduled_by is who booked it.

To learn about changes without polling, subscribe to the lead.*, account.* and meeting.* events by webhook. The format of each one is in Events.