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
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 - Send in a website form submission:
POST /site-leads - List the unclaimed leads:
GET /leads/pond - Claim a lead from the pond:
POST /leads/{id}/claim - Who gets new leads:
GET /leads/routing
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
Scope: leads.write · Role:
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 |
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
Scope: leads.write · Role:
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 |
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
Scope: crm.read
Parameters
| Name | In | Type | |
|---|---|---|---|
limit |
query | integer | How many to answer with, 1 to 200. Default 50. |
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
Scope: crm.write · Role:
Parameters
| Name | In | Type | |
|---|---|---|---|
id (required) |
path | string |
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
Scope: crm.read
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