updateLead
Idempotent
Update a lead record by its ID. Only specified fields are modified; omitted fields stay unchanged. Use _clear_fields to clear specific fields to empty.
Instructions
Update a lead - Update an existing lead record by ID. Fields omitted are untouched.
Required: lead_id.
Custom (form-defined) lead fields — e.g. wizard-style hidden match_* fields — live in users_meta with database=leads and database_id=<lead_id>. Use updateUserMeta / createUserMeta for those. Rule: Forms § Form classes → Custom-field storage covers the pattern.
See also: createLead, deleteLead, matchLead, updateUserMeta.
Returns: { status: "success", message: {...updatedRecord} }.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lead_id | Yes | ||
| lead_name | No | Submitter's full name. | |
| lead_email | No | Submitter email address. | |
| lead_phone | No | Submitter phone number. | |
| lead_message | No | Submitter's detailed request — what they typed describing their needs. | |
| lead_location | No | Geocoded location string. BD recomputes the derived geocode columns (`lat`/`lng`/bounding box/`country_sn`/`adm_lvl_1_sn`/`location_type`) when this changes. | |
| lead_more | No | Match-broadcast flag from the submitter's form input (radio/select). `0` = contact only the single matched member (default). `1` = broadcast to multiple matching members. | |
| lead_price | No | Lead price (decimal). `0.00` = free. | |
| top_id | No | Top category ID. Changing this orphans existing `lead_matches` rows — re-run `matchLead` to re-route. | |
| sub_id | No | Sub-category ID. Same `lead_matches` consideration as `top_id`. | |
| lead_notes | No | Owner-to-member notes about the lead (e.g. "phone number verified"). Visible to the matched member; never shown to the submitter. Leave blank unless the user asks. | |
| lead_status | No | Lead status (integer). NON-SEQUENTIAL enum - `3` does NOT exist; do not assume gaps are fillable: - `1` = Pending (received, awaiting action) - `2` = Matched (assigned to members) - `4` = Follow-Up (in progress) - `5` = Sold Out (no capacity) - `6` = Closed (resolved - converted or won't convert) - `7` = Bad Leads (spam/invalid) - `8` = Delete (soft-delete - hides from views) "Sold" / "won" -> `6` (Closed). Spam -> `7`. BD does NOT validate this enum - out-of-set integers are accepted and stored with undefined render behavior. Always use documented values. | |
| _clear_fields | No | Column names to clear to empty string. Available on every `update*` operation. Works on base columns AND EAV/`users_meta` rows (rows preserved with `value=""`). To actually clear a field you MUST use this parameter — sending the field with `""` alone is a no-op (BD drops empty values). To remove a `users_meta` row entirely, use `deleteUserMeta`. See **Rule: Clearing fields**. Example: `_clear_fields: ["h2", "hero_link_url"]`. |