crm.lead.update

What crm.lead.update does

Updates fields on an existing lead: status/stage moves, enrichment from external data, assignment changes, or corrections. The companion to crm.lead.add in every duplicate-handling flow.

Business use cases

• Duplicate-handling: enriching an existing lead when the same client inquires again
• Moving leads through statuses from external qualification systems
• Writing back verification results (phone validation, enrichment services)
• Reassignment sync from external routing engines
• Marking leads processed/exported for downstream systems

Typical fields and parameters

• id — The lead ID to update (from crm.lead.add or a list/search call)
• fields — Only the fields being changed — updates are partial
• STATUS_ID — Lead status; changing it fires stage-scoped automation rules — know what you are triggering
• PHONE / EMAIL — Replaced entirely on update. To append, first get existing values, include them plus the new one; to delete one entry, resend the array with that item's ID and empty VALUE
• params.REGISTER_SONET_EVENT — 'Y' to reflect the change in the activity stream

Example workflow

1. Repeat inquiry arrives; duplicate check finds lead 20517
2. crm.lead.get retrieves current PHONE array and fields
3. New phone appended to the existing array locally
4. crm.lead.update with id 20517, merged PHONE, and updated SOURCE_DESCRIPTION
5. crm.timeline.comment.add logs 'Repeat inquiry from Dubizzle listing X' for the agent

Example request

POST .../crm.lead.update.json

{
  "id": 20517,
  "fields": {
    "STATUS_ID": "IN_PROCESS",
    "UF_CRM_LAST_INQUIRY": "2026-07-07T14:30:00+04:00",
    "PHONE": [
      { "ID": "3311", "VALUE": "+971501234567", "VALUE_TYPE": "MOBILE" },
      { "VALUE": "+971529876543", "VALUE_TYPE": "MOBILE" }
    ]
  },
  "params": { "REGISTER_SONET_EVENT": "Y" }
}

Example response

{ "result": true, "time": { ... } }
// true on success; an error object otherwise. Note: result true
// does NOT mean every field applied — invalid UF names are ignored.

Field mapping notes

• The most dangerous pitfall: sending PHONE with only the new number erases existing numbers. Always read-merge-write multi-value fields
• Invalid field names fail silently — result is true, the field just isn't set. Verify writes on critical fields
• STATUS_ID changes trigger automations; batch-updating statuses can fire hundreds of robots — throttle or disable rules during migrations

Security notes

• Update permissions follow the webhook user's role — a service account with 'all leads' write access is powerful; scope it deliberately
• Log before/after values for audited fields; updates have no built-in undo

Common errors

• result: true but field unchanged — Wrong field name or wrong value format for the field type — check crm.lead.fields and test on one record
• 'Not found' error — Lead deleted or converted (converted leads are no longer updatable as leads) — handle both cases in duplicate flows
• Phone numbers disappearing — Multi-value replacement — you sent a partial array. Read-merge-write
• Automation storm during bulk update — Stage-scoped robots fired en masse — pause rules or update in off-hours with throttling

Production implementation tips

• Wrap get + update in one batch call to halve latency in enrichment flows
• For high-frequency updates to the same lead (e.g. chat status), debounce — Bitrix24 record locking will punish rapid successive writes
• Keep an 'integration updated at' custom field so admins can see external writes at a glance

Webhook or OAuth app?

Same rule as creation: webhook for controlled server-to-server flows, OAuth app for long-lived, multi-user, or distributable integrations.

Full decision guide: webhook vs OAuth app in Bitrix24.

When to use a queue worker

Needed when updates arrive in bursts (bulk qualification, mass sync). Serialize updates per-record in the queue to avoid write conflicts.

How Tech Titan can help

Tech Titan builds production Bitrix24 integrations around crm.lead.update and its siblings — with authentication, field mapping, queue workers, retry logic, duplicate handling, and structured logs as standard. If this method is on your critical path, bring the requirement to a free audit call and leave with an architecture sketch.