# 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.

Base URL: `https://workspace.brokerandagent.com/api/public/v1`. Every call needs an [API key or OAuth token](https://brokerandagent.com/developers/api/authentication).

- [Send in a lead (Follow Up Boss events payload)](#send-in-a-lead-follow-up-boss-events-payload): `POST /events`
- [Send in a website form submission](#send-in-a-website-form-submission): `POST /site-leads`
- [List the unclaimed leads](#list-the-unclaimed-leads): `GET /leads/pond`
- [Claim a lead from the pond](#claim-a-lead-from-the-pond): `POST /leads/{id}/claim`
- [Who gets new leads](#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 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 |  |

```bash
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](https://brokerandagent.com/developers/api/reference/objects#contact) } |
| `201` | A new contact. | { `contactId`: string, `created`: `true`, `contact`: [Contact](https://brokerandagent.com/developers/api/reference/objects#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 |  |

```bash
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`. |

```bash
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](https://brokerandagent.com/developers/api/reference/objects#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 |  |

```bash
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`

```bash
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](https://brokerandagent.com/developers/api/reference/objects#routingrule), `fallback`: `owner`, `pond`, `businessHours`: [BusinessHours](https://brokerandagent.com/developers/api/reference/objects#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). |  |

---

Source: https://brokerandagent.com/developers/api/reference/leads
