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
leads:read
Query parameters
Response 200
Create a lead
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_ERRORand no lead is created.
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. 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:
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:
assignedToId— assigned directly to that member.roundRobinId— assigned through that pool. The target is explicit, so it is honored even if the pool has no connections, and the pool’sassignInboundLeads/assignManualLeadsflags are bypassed.- Neither — generic auto-assignment: the lead is routed to an active pool with
assignInboundLeadsenabled. A pool with no connections acts as the catch-all “generic inbound” pool, so you can distribute API leads without configuring any webhook connection.
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.
Common errors
400 VALIDATION_ERROR— invalid email, both email and phone missing,assignedToIdis not a member of this organization, orstageIddoes 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 withX-FlowEstate-Source: api). - On merge: no
lead.created— nothing was created. There is nolead.updatedfor 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. ItsautoAssignedflag istruewhen the round robin picked the participant andfalsefor an explicitassignedToId, so you can distinguish the two downstream.
lead.assigned, never lead.created. Reconcile on the outcome of your own call rather than on the events.
Get a lead
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
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
stageIdchanged:lead.stage_changed. - If
statuschanged towon:lead.won. Tolost:lead.lost. - If
assignedToIdchanged:lead.assigned(when set) orlead.unassigned(when cleared).
Delete a lead
leads:write.
Response 200
Webhook side effects
Alead.deleted event is dispatched.
Search a lead
leads:read. Designed for Zapier / Make “Find Lead” steps.
Query parameters
At least one of these is required:Response 200
List activities
leads:read. Lists timeline activities (notes, calls, emails, meetings, system events).
Query parameters
Response 200
Add a note
leads:write.
Request body
content is required, 1..5000 chars.
Response 201
Webhook side effects
Alead.note_added event is dispatched.
Log a communication
leads:write. Records a phone call, email, meeting, or social-media message against the lead’s timeline.
Request body
Response 201
Webhook side effects
Alead.communication_logged event is dispatched.
Update commercial follow-up
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—stageIdis 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
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—expectedno 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.