Skip to main content
The lead is the central resource of FlowEstate. Every endpoint on this page operates inside the calling organization’s tenant — you cannot read or write leads from another organization with the same key.
A personal credential only sees the caller’s current portfolio (assigned, not disabled). List, search, get, activities, notes, communications, commercial, and enrichment all use that filter. Outside the portfolio → 404 NOT_FOUND. Creating or deleting leads is not available on a personal credential.

List leads

Scope: leads:read

Query parameters

Response 200


Create a lead

Scope: leads:write At least one of email or phone is required. Empty strings are treated as missing.

Request body

Source field semantics. FlowEstate accepts any string for source. Known LeadSource values are stored as-is. Unknown values are stored as other on the enum column, with the original string preserved in sourceMetadata.providedSource. This lets you keep your own UTM/campaign mapping without losing data.

Pipeline stage

stageId is optional and behaves in two steps:
  • Omitted — the lead lands in the organization’s default pipeline stage. It is never created without a stage, so it always shows up in the organization’s funnel reports.
  • Provided — the stage must belong to the calling organization’s pipeline. A stage from another tenant, or one that no longer exists, is rejected with 400 VALIDATION_ERROR and no lead is created.
This is a change in behaviour. Until this release, a POST /leads without stageId created the lead with no stage at all, and a stageId that did not belong to the organization was stored as-is. Leads created that way stayed invisible to funnel reporting. New leads no longer can be.
Existing leads are untouched — this applies to creation only. To move a lead afterwards, use PUT /leads/{leadId}.

Deduplication and merge

A lead is identified by its contact identity: the email (lowercased) or the phone reduced to digits. Posting a contact that already exists in your organization does not create a second lead — the call merges into the existing one and returns it.
This is a change in behaviour. Until this release, posting the same contact twice left two leads. A retry from your automation, or the same form submitted twice, no longer duplicates.
The merge only ever fills empty fields. A field the existing lead already carries is never overwritten, so a value someone typed by hand always wins over one that arrives later through the API. customFields merges key by key: keys the lead does not have are added, keys it already has are left alone — including keys whose value is null or "". Three fields are never merged: status, stageId and firstWonAt. They say where the lead sits in the pipeline, which is the organization’s decision, not the caller’s. Use PUT /leads/{leadId} to move a lead. The response tells you which of the two happened:
The status code is 201 in both cases. Check outcome, not the status code, to tell them apart.
Matching is per organization: the same email in two different tenants is two different people. Two calls that race on the same contact are serialized, so concurrency cannot produce a duplicate either. A merge does not consume a plan slot, so an organization at its lead cap can still enrich the leads it already has.

Round robin distribution

POST /leads runs the round robin end to end in a single call — it creates the lead, assigns it through a pool’s rotation, and emits lead.assigned so your downstream automation (for example, an agent WhatsApp notification) fires. No universal lead webhook or middleware bridge is required. When the lead has no owner, assignment is resolved in this order:
  1. assignedToId — assigned directly to that member.
  2. roundRobinId — assigned through that pool. The target is explicit, so it is honored even if the pool has no connections, and the pool’s assignInboundLeads / assignManualLeads flags are bypassed.
  3. Neither — generic auto-assignment: the lead is routed to an active pool with assignInboundLeads enabled. A pool with no connections acts as the catch-all “generic inbound” pool, so you can distribute API leads without configuring any webhook connection.
If no pool matches — or the matched pool has no eligible participant — the lead is created unassigned. Assignment is best-effort: it never fails lead creation. This runs on a merge too. If the call merged into a lead that had no owner yet, the round robin still assigns it — so a repeated post can be what finally routes a lead that arrived unassigned.

Response 201

assignedToId is the assigned member (or null if the lead was left unassigned). roundRobinId is the pool the lead was assigned through (null for an explicit assignedToId or when no assignment happened). assignment is assigned-now when this call made the assignment, pre-existing when the lead already had an owner, and none when nobody was assigned.
The same call for a contact that already existed, where the lead had no company or job title on file:

Common errors

  • 400 VALIDATION_ERROR — invalid email, both email and phone missing, assignedToId is not a member of this organization, or stageId does not belong to this organization. All validated before the lead is created.
  • 403 PLAN_LIMIT_REACHED — the organization is at its lead cap. A merge is never blocked by this: no lead is created, so no slot is consumed. Don’t retry — the verdict cannot change until the plan is upgraded. See Plan-limit errors.

Webhook side effects

  • On create: lead.created (dispatched with X-FlowEstate-Source: api).
  • On merge: no lead.created — nothing was created. There is no lead.updated for the enrichment either.
  • If this call assigns the lead (via assignedToId, roundRobinId, or generic auto-assignment): lead.assigned. This fires on a merge too, when the lead it merged into had no owner yet. Its autoAssigned flag is true when the round robin picked the participant and false for an explicit assignedToId, so you can distinguish the two downstream.
So a repeated post fires either nothing or lead.assigned, never lead.created. Reconcile on the outcome of your own call rather than on the events.

Get a lead

Scope: leads:read. Returns the same shape as a list item. 404 NOT_FOUND if the lead doesn’t exist or belongs to another org.

Update a lead

Scope: leads:write. Same body as create, all fields optional. Must provide at least one field. The contact-identity rule (email or phone) still applies after the merge. Pass null to clear a field; omit it to leave it untouched.

Webhook side effects

  • Always: lead.updated.
  • If stageId changed: lead.stage_changed.
  • If status changed to won: lead.won. To lost: lead.lost.
  • If assignedToId changed: lead.assigned (when set) or lead.unassigned (when cleared).

Delete a lead

Scope: leads:write.

Response 200

Webhook side effects

A lead.deleted event is dispatched.

Search a lead

Scope: leads:read. Designed for Zapier / Make “Find Lead” steps.

Query parameters

At least one of these is required:

Response 200


List activities

Scope: leads:read. Lists timeline activities (notes, calls, emails, meetings, system events).

Query parameters

Response 200


Add a note

Scope: leads:write.

Request body

content is required, 1..5000 chars.

Response 201

Webhook side effects

A lead.note_added event is dispatched.

Log a communication

Scope: leads:write. Records a phone call, email, meeting, or social-media message against the lead’s timeline.

Request body

Response 201

Webhook side effects

A lead.communication_logged event is dispatched.

Update commercial follow-up

Scope: leads:write. Updates pipeline/commercial fields only. Does not change assignment, source, consents, or customFields.

Request body

At least one field is required.

Response 200

Common errors

  • 400 INVALID_STAGE — stageId is not a stage of this organization.
  • 409 FOLLOW_UP_ACTIVE — an active follow-up exists; complete it or clear it first.
  • 404 NOT_FOUND — lead missing or outside the caller’s portfolio.

Enrich a lead

Scope: leads:write. Fills empty contact fields by default. To overwrite a stored value, include it in correct with the current expected value.

Request body

Response 200

skipped lists fields that were sent but neither empty nor successfully corrected.

Common errors

  • 409 STALE_CORRECTION — expected no longer matches; re-read the lead and retry.
  • 409 IDENTITY_CONFLICT — email or phone already belongs to another lead. The other record is not returned.
  • 404 NOT_FOUND — lead missing or outside the caller’s portfolio.