Connecting custom lead sources via webhooks

Your webhook URL

Create a connection on the Webhooks card (Marketing › Integrations › Webhooks › Add connection). The page shows a URL of this form, with your own key:

POST https://<your-bmexa-api>/api/v1/leads/inbound/<key>

Payload

Send a JSON body. Name and phone are required; everything else is optional.

curl -X POST "https://<your-bmexa-api>/api/v1/leads/inbound/<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Asha Mehta",
    "phone": "9810000000",
    "email": "asha@example.com",
    "city": "Noida",
    "project": "Aranya Greens",
    "budget": "12000000",
    "purpose": "Self use",
    "campaign": "Diwali offer",
    "message": "Interested in 3 BHK",
    "other_fields": { "Preferred floor": "High", "Visit day": "Sunday" }
  }'

Response

• 200 { "id": "…", "enquiryId": "ENQ-…" } when a new lead was created.
• 200 { "id": "…", "enquiryId": "ENQ-…", "duplicate": true } when the phone already has an open enquiry: the message and fields were added as a remark, and a lead clash was raised if the source differs.
• 400 when name or phone could not be read. The message names the missing fields.
• 401 when the key is missing, wrong or belongs to a disabled connection.
• 429 when a key sends more than 60 requests a minute.

Key in a header instead of the URL

If your system can set headers, keep the key out of the URL:

POST https://<your-bmexa-api>/api/v1/leads/inbound
x-lead-key: <key>
Content-Type: application/json

Project, campaign and budget

A project name that matches one of your projects (case-insensitive) is linked as the lead's primary interest, with the budget as its range. A campaign name that matches one of your marketing campaigns overrides the connection's default campaign for that lead. Unknown names are kept as text.

Field names we understand

You rarely have to rename anything. Name may arrive as name, full_name, your-name, first_name plus last_name, Client Name. Phone may be phone, mobile, tel, contact number, whatsapp. Email may be email or e-mail. Message may be message, notes, comments, enquiry, requirements. City, project, budget, purpose and campaign are matched the same way.

Nested payloads are flattened first, so a Typeform answer list, a Jotform q3_fullName, a Wix data.contact.phone or an Elementor fields.name.value all work. If nothing is labelled, BMexa still picks out anything that looks like an email address or a phone number.

What happens when a lead arrives

• The lead is created in Clients within seconds, with the source name on the record and on the alert.
• The person you chose on the connection is assigned and gets an in-app alert (and a browser push if they allowed it). If they turned on Lead alerts on WhatsApp, they also get the lead on WhatsApp from BMexa’s number, or from your own connected number when its card has the lead-alert option on; the client’s phone and email are masked in that message.
• Every field we recognise fills the client record: name, phone, email, city, project, budget, purpose, message, campaign. Any other field is kept as a form field and written to the remarks, so nothing the form captured is lost.
• A phone number that already has an open enquiry does not create a second lead: the message is added as a remark on the existing one, and if it came from a different source a lead clash is raised for the manager to settle.
• Assignment rules, duplicate settings and auto-replies apply to these leads as they ship (see Automations & WhatsApp).