# Send leads (Follow Up Boss-compatible)

> Send leads with the same payload you send Follow Up Boss, or from a website form. They run through routing, tagging and follow-up like any other lead.

`POST /events` takes **Follow Up Boss's event payload**. Send leads to Broker & Agent the way you send them to Follow Up Boss: the same request, with our URL and key. Many lead vendors send only to Follow Up Boss's own address, so this works where your lead source lets you set the address, like custom forms, ISA tools and your own code.

A lead sent this way takes the same path as a lead from your website: it's matched to an existing contact by email, routed by your lead rules, tagged with its source, and started on your new-lead follow-up.

## Send a lead

```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": "Zillow Flex",
    "type": "Inquiry",
    "message": "Wants to see 41 Oak St this weekend",
    "person": {
      "firstName": "Dana", "lastName": "Reyes",
      "emails": [{ "value": "dana@example.com" }],
      "phones": [{ "value": "(816) 555-0100" }],
      "tags": ["relocation"]
    },
    "property": { "street": "41 Oak St", "city": "Kansas City", "state": "MO" }
  }'
```

A person needs at least a name, an email or a phone.

| Answer | When |
|---|---|
| `201` with the contact | A new contact was created |
| `200` with the contact | The email matched an existing contact; the inquiry lands on their timeline |
| `202 { "ok": true }` | The key is a lead-capture key (**Leads in only**), or the match is a contact this key's person can't see. The lead still lands |
| `422` | There's no name, email or phone |

The property's city and price reach your lead rules, so a rule's **Only when** conditions (area and price) work on these leads too.

> [!TIP]
> Give each lead source its own **Leads in only** key. It can send leads and read nothing, so a leaked key can't expose your book. See [Authentication](https://brokerandagent.com/developers/api/authentication#what-a-key-can-reach).

## Coming from Follow Up Boss

Only lead intake carries over. Here's what a lead source that already sends to Follow Up Boss has to change.

1. **The key.** Use one of ours; a **Leads in only** key is best. Follow Up Boss's Basic auth works as it is, with our key as the username and an empty password.
2. **The full address.** Send to `https://workspace.brokerandagent.com/api/public/v1/events`. There's no short `/v1/events` address on an API host.
3. **The answer.** We answer with `{ contactId, created, contact }`, not Follow Up Boss's person object with a numeric id. Anything that reads the answer needs to read ours.
4. **The other calls.** `/people`, `/notes`, `/calls` and `/deals` in Follow Up Boss's shape don't exist here. Our [contacts, tasks, appointments and transactions](https://brokerandagent.com/developers/api/reference/contacts) calls have their own shapes.

### What carries over

| Field | Carries over |
|---|---|
| `source` (or `system`), `type`, `message` | Yes |
| `person`: names, emails, phones | Yes |
| `person.tags` | Yes, up to 10 |
| `property`: street, city, state, price, MLS number and URL | Yes |
| Zip and the other property fields | No |
| Person stage, assignee and addresses | No |
| `campaign`, `occurredAt` | No |
| `X-System` headers | Ignored |

## Event types

- **A seller type** (anything with "seller", "home value" or "CMA") marks the lead as selling. Rentals and leases are read from the type and message. Everything else is a buyer.
- **Activity types** (`Viewed Property`, `Viewed Page`, `Visited Website`, `Saved Property`, `Property Search`, `Saved Property Search`) land on the timeline as activity.
- **`Unsubscribed`** opts an email out. It needs the `crm.write` scope and only affects a contact the credential's person can see.

The same inquiry from the same person within 10 minutes adds no second note and sends no second alert.

## Website form leads

`POST /site-leads` takes one form submission from a website's server. It's what Broker & Agent websites send, with a lead-capture key, and any website can use it. The key decides the workspace.

```json
{
  "source": "agent-site",
  "lead": {
    "name": "Rosa Diaz", "email": "rosa@example.com", "phone": "941-555-0177",
    "interest": "Buying", "message": "Can I see it this weekend?",
    "pageUrl": "https://example.com/homes/123?utm_source=google",
    "formSource": "listing-inquiry", "consent": true,
    "submissionId": "b1f0c…", "visitorId": "v_…", "intent": "buy",
    "listing": { "mlsId": "A4612345", "address": "123 Main St", "city": "Sarasota",
                 "state": "FL", "zip": "34236", "price": 450000,
                 "url": "https://example.com/homes/123", "lease": false }
  }
}
```

- **`intent`** is `buy`, `sell`, `rent`, `both` or `owner`. Without it, `interest` is read. An owner (property management) arrives tagged `property-owner`.
- **UTM tags** come from `pageUrl`, and the listing lands on the lead's note.
- **`visitorId`** ties the visitor's earlier browsing and chat on the site to the lead.
- **`consent: true` with a phone** keeps a record that the visitor agreed to texts: the form's wording, the page and when.
- **`submissionId`** is the deduplication key, kept 30 days, so a retry lands once. A copy that arrives while the first is still being handled may get `409 in_progress` with `Retry-After`.
- **The answer** is `200 { "id": "<contactId>", "created": true | false }`. A lead-capture key gets `{ "id": null, "created": null }`. A lead with no name, email or phone is `422`.

A site can also send its leads with `POST /events` or `POST /contacts` and a lead-capture key.

## Related

- [Retrying safely](https://brokerandagent.com/developers/api/idempotency)
- [Webhooks](https://brokerandagent.com/developers/webhooks): get `lead.created` the moment a lead lands.

---

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