Leads API

Leads in the Broker & Agent API: send in a lead (follow up boss events payload); send in a website form submission; list the unclaimed leads; and more.

Generated from the product on Nov 17, 2026

Base URL: https://workspace.brokerandagent.com/api/public/v1. Every call needs an API key or OAuth token.

Send in a lead (Follow Up Boss events payload)#

POST /events

Accepts the Follow Up Boss events payload, so anything that can deliver a lead to FUB can deliver it here with a URL swap. The lead runs the real arrival path: dedupe by email, lead routing, source tagging and the new-lead follow-up. A copy of the same inquiry within 10 minutes adds no second note or alert. An Unsubscribed event puts the email on the opt-out list and nothing else; it needs crm.write (403 insufficient_scope otherwise) and reaches only a contact the credential’s person can see, answering 202 either way.

Scope: leads.write · Role: agent or above

Body

Field Type
source string or null Where the lead came from, e.g. Zillow Flex. Becomes the contact’s source.
system string or null Read as the source when source is absent.
type string or null Inquiry, Seller Inquiry, Property Inquiry, Registration, Viewed Property, Saved Property, Property Search, Unsubscribed and the rest of FUB’s types.
message string or null
description string or null Read as the message when message is absent.
person object or null
property object or null
pageUrl string
Shell
curl -X POST https://workspace.brokerandagent.com/api/public/v1/events \
  -H "Authorization: Bearer bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":"Open house","system":"…"}'

Responses

Status Returns
200 Landed on an existing contact. { contactId: string, created: false, contact: Contact }
201 A new contact. { contactId: string, created: true, contact: Contact }
202 Received. A lead-capture credential, a match the credential can’t see, and an Unsubscribed event all get this and nothing more. { ok: true }
400 The body isn’t a JSON object (bad_json), or the Idempotency-Key is malformed (bad_idempotency_key).
401 No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended).
403 The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience).
409 A request with this Idempotency-Key is still being handled (idempotency_in_progress, with Retry-After), or the call conflicts with the record’s state (flow_off, in_progress).
422 A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused).
429 Too many requests for this credential; wait for Retry-After (rate_limited).

Send in a website form submission#

POST /site-leads

One form submission from an agent website’s server. submissionId is the dedupe key, kept 30 days: a retry, or the same submission from the visitor’s browser, lands once and answers the same.

Scope: leads.write · Role: agent or above

Body

Field Type
source string or null Cut to 60 characters.
agentId string or null Cut to 100 characters.
tenantId string or null Cut to 64 characters.
lead (required) object
Shell
curl -X POST https://workspace.brokerandagent.com/api/public/v1/site-leads \
  -H "Authorization: Bearer bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lead":{}}'

Responses

Status Returns
200 Landed. id and created come back only to a credential that can read that contact. { id: string or null, created: boolean or null }
400 The body isn’t a JSON object (bad_json), or the Idempotency-Key is malformed (bad_idempotency_key).
401 No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended).
403 The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience).
409 A request with this Idempotency-Key is still being handled (idempotency_in_progress, with Retry-After), or the call conflicts with the record’s state (flow_off, in_progress).
422 A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused).
429 Too many requests for this credential; wait for Retry-After (rate_limited).

List the unclaimed leads#

GET /leads/pond

The business’s leads nobody owns yet, in the ponds the credential’s person can see, newest first. total counts them all.

Scope: crm.read

Parameters

Name In Type
limit query integer How many to answer with, 1 to 200. Default 50.
Shell
curl https://workspace.brokerandagent.com/api/public/v1/leads/pond \
  -H "Authorization: Bearer bak_YOUR_KEY"

Responses

Status Returns
200 The pond. { leads: array of PondLead, total: integer }
401 No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended).
403 The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience).
429 Too many requests for this credential; wait for Retry-After (rate_limited).

Claim a lead from the pond#

POST /leads/{id}/claim

Makes a pond lead the credential’s person’s own, at once. The first claim wins: a lead someone else took, or one not in a pond they can see, answers 409 and changes nothing. Asking again for a lead that’s already yours answers 200, and finishes anything an earlier try left undone.

Scope: crm.write · Role: agent or above

Parameters

Name In Type
id (required) path string
Shell
curl -X POST https://workspace.brokerandagent.com/api/public/v1/leads/ID/claim \
  -H "Authorization: Bearer bak_YOUR_KEY"

Responses

Status Returns
200 Claimed. { lead: object }
400 The body isn’t a JSON object (bad_json), or the Idempotency-Key is malformed (bad_idempotency_key).
401 No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended).
403 The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience).
404 No such record, or one the credential’s person can’t see (not_found).
409 A request with this Idempotency-Key is still being handled (idempotency_in_progress, with Retry-After), or the call conflicts with the record’s state (flow_off, in_progress).
422 A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused).
429 Too many requests for this credential; wait for Retry-After (rate_limited).

Who gets new leads#

GET /leads/routing

The routing rules in the order they’re tried (the first whose source and conditions match a lead decides), each rule’s conditions (area, price, intent, business hours), who each deals to today and who’s next, and where a lead goes that no rule catches: the owner of a workspace with no teams, else the pond. businessHours is what a rule’s hours condition reads. The rules are changed in the app.

Scope: crm.read

Shell
curl https://workspace.brokerandagent.com/api/public/v1/leads/routing \
  -H "Authorization: Bearer bak_YOUR_KEY"

Responses

Status Returns
200 The rules. { rules: array of RoutingRule, fallback: owner, pond, businessHours: BusinessHours }
401 No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended).
403 The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience).
429 Too many requests for this credential; wait for Retry-After (rate_limited).

Something missing or wrong? Email support@brokerandagent.com and we’ll fix it.