Copy page

Guides

Capture leads from your website or ads

Send a lead from your website form or an ad platform straight onto the broker's Leads board. This guide covers the one request you need, how BrokerPlus handles a person who is already in the book, and what to do when a request fails.

How it works

Code
Website form or ad platform  ->  Your server  ->  POST /v1/leads  ->  BrokerPlus

Your server receives the form and makes one POST /v1/leads request. BrokerPlus creates the contact and the lead together, files the lead with source: "api", runs your New Lead Created automations, and sends the lead.created webhook.

Never call the API from the browser. A key in a web page is a key every visitor can copy, and it can read the broker's whole book. Post the form to your own server and keep the key there.

Before you start

1. Create a key for this form only, named after it (for example Website lead form), and give it the leads_only limit. See Authentication.
2. Pick the broker who gets the leads. A key acts as the broker who created it, and that broker owns every lead it creates.
3. Put the key in an environment variable on your server, for example BROKERPLUS_API_KEY.

Send a lead

first_name is the only required field. Send email whenever you have it: it is how BrokerPlus recognises a person who is already in the book.

Add an Idempotency-Key header built from your form tool's submission id. If your server retries after a timeout, the API replays the first response instead of creating a second lead. See Idempotency and batch.

The API answers 201 with the lead:

Code
{
  "success": true,
  "data": {
    "object": "lead",
    "id": "cmlead7q...",
    "contact_id": "cmcontact...",
    "first_name": "Jordan",
    "last_name": "Client",
    "email": "jordan@example.com",
    "phone": "+1 587 555 1234",
    "source": "api",
    "stage_id": "cmstage...",
    "service_type": "Purchase",
    "first_time_buyer": true,
    "next_follow_up_at": null,
    "additional_details": "Wants to close in June.",
    "archived_at": null,
    "submission_count": 1,
    "submission": {},
    "created_at": "2026-10-07T15:04:11.000Z",
    "updated_at": "2026-10-07T15:04:11.000Z"
  }
}

The name, email, and phone are read from the lead's contact. If the email already belonged to someone in the book, you get that person's details back, not the ones you sent.

When the person is already in the book

You don't need to search first. BrokerPlus matches on email:

The person you send	What BrokerPlus does
An email no contact has	Creates a contact and a lead.
The email of a contact with no open lead	Reuses that contact and opens a lead on it.
The email of a contact who already has an open lead	Reuses that lead, adds 1 to submission_count, and does not send a second webhook.
No email	Creates a contact and a lead. Without an email there is nothing to match on.

When BrokerPlus reuses a contact, it leaves that contact's name and phone alone. It does write service_type, next_follow_up_at, and additional_details on the lead, and a field you leave out is cleared. Send all three on every request.

The idempotency key and the email match solve different problems. The key stops a retry of one submission from making two leads. The email match stops a second submission from the same person from making a second lead.

Look a person up before you send

Sometimes you need to know who someone is first, for example to greet a past client differently. Search contacts by email or phone:

Code
{
  "success": true,
  "data": [
    {
      "object": "contact",
      "id": "cmcontact...",
      "kind": "individual",
      "types": ["client"],
      "first_name": "Jordan",
      "last_name": "Client",
      "email": "jordan@example.com",
      "phone": "+1 587 555 1234"
    }
  ],
  "pagination": { "total": 1, "page": 1, "page_size": 50, "total_pages": 1 }
}

The response is trimmed to a few fields.

• email ignores case and also matches a contact's additional email addresses.
• phone compares the last 10 digits, so +1 (587) 555-1234 and 5875551234 match.
• GET /v1/leads takes the same email and phone filters, matched against each lead's contact.
• No match is an empty data list, not a 404.

Leads from ads

Facebook, Google, and other ad platforms post each lead to a URL you own. Point that URL at your server, not at BrokerPlus, and make the same POST /v1/leads request from there.

• Use the platform's lead id as the Idempotency-Key, for example meta-lead-1234567890. Ad platforms do deliver the same lead more than once.
• Acknowledge the platform first, then send the lead to BrokerPlus. A platform that waits on BrokerPlus can time out and send the lead again.
• Record where the lead came from in custom fields, so the broker can filter and report on it.

Record the source and the click id

POST /v1/leads takes custom_fields, an object of values keyed by field key. A lead's custom fields are its contact's custom fields.

1. In BrokerPlus, create a contact custom field for each value, for example lead_source and click_id.
2. Call GET /v1/custom-fields?entity=contact to get each field's exact key.
3. Send the values with the lead.

Each value is text, in the same format PATCH /v1/contacts/{id}/custom-fields/{key} takes. A select field takes one of its options.

The API checks every key and value before it creates anything. One unknown key or bad value refuses the whole request with 400 VALIDATION_ERROR, and details.custom_fields says what to fix:

Code
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Fix the custom_fields named in details",
    "details": {
      "custom_fields": {
        "click_id": "No contact custom field has this key. List the keys with GET /v1/custom-fields?entity=contact."
      }
    }
  }
}

Nothing was created, so fix the field and send the request again with the same Idempotency-Key.

When a request fails

Response	What to do
400 VALIDATION_ERROR	Fix the field that details names. Sending the same body again won't help.
401 UNAUTHORIZED	The key was revoked, or its broker was deactivated. Create a new key.
429 RATE_LIMITED	Wait Retry-After seconds, then send the same request.
A timeout or a 5xx	Send the same request again with the same Idempotency-Key.

Keep each submission on your server until a request succeeds. A lead your server drops is a lead no broker ever sees. Every code is listed on Errors.

Lead forms

A lead form is a form that BrokerPlus hosts for the broker. Put its url in an iframe on a website, or link to it, and each answer arrives on the Leads board with lead_form_id set. You can build, change, and delete forms through the API, with the same checks as the form builder.

Code
curl -X POST https://api.mos.getbrokerplus.ca/v1/lead-forms \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Renewal quote" }'

Code
{
  "success": true,
  "data": {
    "object": "lead_form",
    "id": "cmg8k2f1x0001lf0j3x8w9q2a",
    "name": "Renewal quote",
    "slug": "renewal-quote",
    "url": "https://mos.getbrokerplus.ca/embed/f/renewal-quote",
    "enabled": true,
    "owner_user_id": "cmg1alexbroker0001",
    "owner_name": "Alex Broker",
    "config": { "headline": "Get in touch", "questions": ["..."], "thanks": { "autoReply": false } },
    "lead_count": 0,
    "recent_lead_count": 0,
    "converted_count": 0,
    "newest_lead_at": null,
    "created_at": "2026-10-09T15:02:11.000Z",
    "updated_at": "2026-10-09T15:02:11.000Z"
  }
}

• config is the whole form, in the builder's own format. To change it, read it with GET /v1/lead-forms/{id}, change it, and send all of it back with PATCH. A field that fails a check is named in details, for example config.questions.
• Every form asks everyone for a first name and an email. BrokerPlus refuses a form that does not.
• PATCH with enabled: false hides the form. Its leads stay in the book.
• DELETE removes the form, and its page stops working at once. Its leads stay, with no lead_form_id.
• List the leads that a form brought in with GET /v1/leads?lead_form_id={id}.

The auto-reply

A form can send an email or a text to each person who fills it in. That reaches a client, so a write cannot turn it on: save the form with thanks.autoReply set to false, then call POST /v1/lead-forms/{id}/turn-on-auto-reply. The reply is on when the response comes back, and the response is the form. While the reply is on, you can turn it off with PATCH, but you cannot change what it says. A key with the no_sending limit cannot turn it on.

Hear about every new lead

Subscribe a webhook to lead.created to get a signed POST whenever BrokerPlus creates a lead from any source: your form, a BrokerPlus form, or a call. See Webhooks.