createLead
Create a new lead record to import leads from external forms or CSV. Provide submitter name, email, phone, message, location, and category. Supports silent creation with optional email notifications and member matching.
Instructions
Create a lead - Create a new lead record. Writes live data.
Use when: importing leads from an external form, CSV, or web-scrape. Default is SILENT - no notification emails fire unless you pass send_lead_email_notification=1, and no member routing happens unless you pass auto_match=1 (inline) or call matchLead afterward. top_id (category) is required - look it up via listTopCategories.
Required: lead_name, lead_email, lead_phone, lead_message, lead_location, top_id.
Parameter interactions:
top_id- category ID; discover vialistTopCategoriesAll 6 required fields (
lead_name,lead_email,lead_phone,lead_message,lead_location,top_id) must be supplied togetherResponse includes
lead_idANDtoken- token may be needed for customer-facing URLsAfter creating, call
matchLeadto trigger member notifications
See also: updateLead (modify existing).
Operational rules (from BD support article 12000091106):
send_lead_email_notification=1- activates lead email notifications to the site admin and/or matched members. Default is off: leads created via API are silent unless this flag is set. For the full auto-matching flow (finds members by category/location and emails them), callmatchLeadseparately after creating the lead (or passauto_match=1on this call to run inline).
Targeting specific members (override auto-match): set users_to_match to a comma-separated list of member IDs or emails (e.g. 6099,6100 or user1@example.com,user2@example.com, mixed OK). This BYPASSES the normal category/location/service-area matching and routes the lead to ONLY those members. Typically paired with auto_match=1 (to run the match step inline) and send_lead_email_notification=1 (to fire the matched-member email). Common pattern when an external system already knows who should receive the lead.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lead_name | Yes | Submitter's full name. | |
| lead_email | Yes | Submitter email address. | |
| lead_phone | Yes | Submitter phone number. | |
| lead_message | Yes | Submitter's detailed request — what they typed describing their needs. | |
| lead_location | Yes | Geocoded location string. BD computes the derived geocode columns (`lat`/`lng`/bounding box/`country_sn`/`adm_lvl_1_sn`/`location_type`) from this. | |
| top_id | Yes | Top category ID. Discover via `listTopCategories`. | |
| send_lead_email_notification | No | Set `1` to fire lead notification emails on create. Default `0` - API-created leads are silent. - With `auto_match=1` or `users_to_match` populated -> matched-member notification fires (if this flag = `1`) - Without a match step -> only admin notification fires (if configured) **For matched-member notifications:** combine this flag with a matching trigger (`auto_match=1` and/or `users_to_match`) - neither alone is sufficient. | |
| auto_match | No | Set to `1` to run the match step inline during create (equivalent to calling `matchLead` immediately after). Default `0` = no match step fires. When combined with `users_to_match`, the match step still fires but the category/location/service-area matching ALGORITHM is bypassed — the lead routes ONLY to the specified members. | |
| users_to_match | No | **ADVANCED - OVERRIDES auto-match.** Comma-separated list of `user_id` values OR member email addresses (mixable) to route this lead to directly. When set, BD skips normal category/location/service-area auto-matching and routes ONLY to these members. Examples: `239` | `6099,6100` | `user1@example.com,user2@example.com` | `239,user1@example.com`. Typically paired with `auto_match=1` (triggers match inline) AND `send_lead_email_notification=1` (fires matched-member email - without the flag, matches record but no email sends). |