Skip to main content
A round robin pool distributes inbound leads across an ordered list of participants using pointer rotation: each pool remembers whose turn is next, assigns the lead to that participant, then advances the pointer to the following participant (wrapping back to the first after the last). The rotation order is the order of the participantIds array. Connections route inbound leads into a pool by matching their origin — a generic webhook, a meta page/form/ad/campaign, an automation provider (Zapier, Make, n8n), or a workflow. When a lead arrives, FlowEstate picks the active pool whose connection matches the lead’s source and assigns it through that pool’s rotation. Every endpoint on this page operates inside the calling organization’s tenant — you cannot read or write round robin pools from another organization with the same key.
Run the round robin end to end over REST — no universal webhook needed. Either let POST /leads create, assign, and emit lead.assigned in a single call (pass roundRobinId to target a specific pool), or create the lead first and call POST /round-robin/assign. Both paths emit the lead.assigned event that triggers your downstream agent notifications. A pool with no connections and assignInboundLeads: true receives these leads as the generic inbound catch-all.

List pools

Scope: round-robin:read. Lists the organization’s round robin pools, newest first.

Query parameters

Request

Response 200

nextParticipantOrder is the 1-based order value of the participant who will receive the next lead. participantCount counts only active participants.

Create a pool

Scope: round-robin:write

Request body

Connection object

Each entry in connections (and the body of POST .../connections) has this shape:
Only one pool per organization may hold the generic webhook connection, and the organization’s universal lead webhook integration must be enabled. Duplicate connections (identical field-for-field) are rejected.

Request

Response 201

Common errors

  • 400 VALIDATION_ERROR — invalid body (empty participantIds, automation connection missing provider, workflow connection missing workflowId, etc.).
  • 400 BAD_REQUEST — a participant or follower is not an organization member, duplicate participants, or duplicate connections.
  • 400 BAD_REQUEST — webhook connection requested but the universal lead webhook integration is not enabled.
  • 409 CONFLICT — the universal webhook connection is already assigned to another pool.

Get a pool

Scope: round-robin:read. Returns the pool with its ordered participants, connections, a settings summary, and assignment stats. 404 NOT_FOUND if the pool doesn’t exist or belongs to another org.

Response 200

Participants are returned in rotation order (order ascending).

Update a pool

Scope: round-robin:write. Body is the create body minus name’s required flag — every field is optional; send only what you want to change. 404 NOT_FOUND if the pool doesn’t exist or belongs to another org.

Request

Reorder the rotation and deactivate the pool:

Response 200

Common errors

  • 400 VALIDATION_ERROR / 400 BAD_REQUEST — same validation rules as create (membership, duplicates, connection requirements).
  • 409 CONFLICT — the universal webhook connection is already held by another pool.

Delete a pool

Scope: round-robin:write. Removes the pool and its participants, connections, and assignment history. 404 NOT_FOUND if the pool doesn’t exist or belongs to another org.

Response 200


Add a connection

Scope: round-robin:write. Adds a single routing connection to an existing pool. Body is the connection object. 404 NOT_FOUND if the pool doesn’t exist or belongs to another org.

Request

Response 201

Common errors

  • 400 VALIDATION_ERROR — automation connection missing provider, or workflow connection missing workflowId.
  • 400 BAD_REQUEST — webhook connection requested but the universal lead webhook integration is not enabled.
  • 409 CONFLICT — an identical connection already exists on this pool, or the universal webhook connection is held by another pool.

Remove a connection

Scope: round-robin:write. 404 NOT_FOUND if the connection doesn’t exist on that pool or belongs to another org.

Response 200


List assignments

Scope: round-robin:read. Lists the pool’s assignment history, newest first.

Query parameters

Response 200

turnOrder is the participant’s order value at the time of assignment. metadata is a JSON-encoded string (or null) describing how the lead matched a connection.

Assign a lead

Scope: round-robin:write. Runs a lead through the matching active pool’s pointer rotation, assigns it to the next eligible participant, advances the pointer, and emits lead.assigned. Use this when the lead already exists (otherwise POST /leads does create + assign in one call).

Request body

Request

Response 200

When a participant is assigned:
When no assignment happens — no active pool matches the source, the matched pool has no eligible participant, or the lead already has an assignee — the response is:
The lead is only assigned if it currently has no assignee. A lead that already has an owner returns { "assigned": false } and is left untouched.

Webhook side effects

On a successful assignment, a lead.assigned event is dispatched (with autoAssigned: true) and an assigned activity is logged on the lead’s timeline. Nothing is emitted when the response is { "assigned": false }.

Common errors

  • 400 VALIDATION_ERROR — leadId is not a UUID, or source is not a known value.
  • 404 NOT_FOUND — the lead does not exist or belongs to another organization.