How do I create a lead in Bitrix24 using REST API?

Call crm.lead.add with a fields object via your inbound webhook URL or OAuth token. The response returns the new lead ID. See the example request above.

How do I set custom fields with crm.lead.add?

Include them in fields using their exact UF_CRM_* names (list them with crm.lead.fields). Multi-select and money fields have specific value formats — check the field type first.

How do I prevent duplicate leads?

Before adding, search by normalized phone/email (crm.lead.list with a filter, or the duplicate-detection methods). On match, update and comment on the existing lead instead of creating.

crm.lead.add — Create Bitrix24 Leads via REST API

What crm.lead.add does

Creates a lead record — the entry point of the CRM funnel. This is the single most used method in capture integrations: website forms, Meta Lead Ads, portal leads, chat inquiries, and missed calls all typically end in a crm.lead.add call.

Business use cases

Website contact and landing-page forms creating leads in real time
Meta Lead Ads delivery with campaign attribution fields
Bayut / Dubizzle / Property Finder portal leads with property details
WhatsApp or chatbot inquiries from unknown numbers
Missed-call capture creating callback leads

Typical fields and parameters

TITLE — Lead title shown in lists — build it informatively, e.g. 'Bayut — 2BR Marina — +9715…'
NAME / LAST_NAME — Client name split; portals often give one string you must split or put in NAME
PHONE / EMAIL — Multi-value fields: arrays of { VALUE, VALUE_TYPE } objects, not plain strings
SOURCE_ID — Source from your crm.status source directory — the foundation of ROI reporting
SOURCE_DESCRIPTION — Free-text detail: campaign name, listing reference, form name
ASSIGNED_BY_ID — Responsible user ID — set it explicitly or let your routing automation assign
UF_CRM_* — Your custom fields: property reference, community, budget, campaign, etc.
params.REGISTER_SONET_EVENT — Set 'Y' so the creation appears in the activity stream and triggers automations that listen for it

Example workflow

Form/portal payload received by your webhook receiver and validated
Phone normalized to E.164; duplicate check via crm.lead.list (or crm.duplicate.findbycomm) on phone/email
If duplicate: update existing lead and add a timeline comment instead
If new: crm.lead.add with mapped fields and source attribution
Store returned ID; Bitrix24 automation rules take over (assignment, first touch, tasks)

Example request

POST https://yourportal.bitrix24.com/rest/1/xxxxxxxx/crm.lead.add.json
Content-Type: application/json

{
  "fields": {
    "TITLE": "Bayut — 2BR Dubai Marina — Ahmed",
    "NAME": "Ahmed",
    "PHONE": [{ "VALUE": "+971501234567", "VALUE_TYPE": "MOBILE" }],
    "EMAIL": [{ "VALUE": "ahmed@example.com", "VALUE_TYPE": "WORK" }],
    "SOURCE_ID": "WEB",
    "SOURCE_DESCRIPTION": "Bayut listing REF-4521",
    "UF_CRM_PROPERTY_REF": "REF-4521",
    "UF_CRM_COMMUNITY": "Dubai Marina"
  },
  "params": { "REGISTER_SONET_EVENT": "Y" }
}

Example response

{
  "result": 20517,
  "time": { "start": 1720340000.12, "finish": 1720340000.34, "duration": 0.22 }
}
// "result" is the new lead ID. On failure you get
// { "error": "...", "error_description": "..." } instead.

Field mapping notes

PHONE and EMAIL are arrays of objects — sending a bare string silently drops the value
SOURCE_ID must match an existing source in the CRM directory; unknown values fall back inconsistently — sync your source list first
Custom field names are UF_CRM_ + your suffix; get exact names from crm.lead.fields, never guess casing
Dates go in ISO 8601 (2026-07-07T12:00:00+04:00); wrong timezones corrupt response-time metrics

Security notes

Create the webhook under a dedicated service account with only crm scope
Never expose the webhook URL in client-side code — form submissions must proxy through your server
Log the payload, never the webhook URL

Common errors

ERROR_CORE / 'Access denied' — Webhook lacks crm scope or the creating user lacks lead creation rights — check both
Field values silently missing after creation — Multi-value fields sent as strings, or wrong UF_CRM_ name — verify against crm.lead.fields output
QUERY_LIMIT_EXCEEDED — You are hitting rate limits — queue creations and use batch for bulk work
Duplicate leads from retried requests — Your retry logic re-sends after timeouts — implement an idempotency check (search by phone + recent window) before add

Production implementation tips

Respond to your form/webhook caller immediately and create the lead from a queue — never make a user wait on Bitrix24
Store the raw source payload (as a note or file) so mis-mapped leads are recoverable
Alert when creation failure rate rises; a silent capture outage is lost revenue by the hour
Build TITLE informatively — it is what agents see in every list view

Webhook or OAuth app?

A scoped inbound webhook under a service account is the standard choice for one-way lead capture. Move to an OAuth app when the integration becomes multi-directional, needs UI, or must survive independent of any user account.

Full decision guide: webhook vs OAuth app in Bitrix24.

When to use a queue worker

Mandatory for ad and portal sources: launch campaigns produce bursts that will breach rate limits if you create leads synchronously. Queue first, create with controlled concurrency.

How Tech Titan can help

Tech Titan builds production Bitrix24 integrations around crm.lead.add 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.

Book Free CRM Audit or Demo API Development service

crm.lead.add