YZ ajanları için: bu sayfanın markdown'ı — /docs-content-en/entities/leads.md dokümantasyon dizini — /llms.txt

Dokümantasyon makaleleri şu anda İngilizce olarak mevcuttur.

Leads

CRM lead management: create, retrieve, update, delete, filter.

Bitrix24 API: crm.item.* Scope: crm

Create lead

POST /v1/leads

Creates a new lead in CRM.

Request fields (body)

Parameter Type Description
title string Lead title
name string Contact first name
lastName string Contact last name
secondName string Middle name
stageId string Lead status — canonical name, the statusId alias is also accepted. Standard: NEW, IN_PROCESS, PROCESSED. A Bitrix24 account may have its own — list: GET /v1/statuses?filter[entityId]=STATUS. In the response the value is returned in the stageId field
opportunity number Amount — canonical name, the amount alias is also accepted. ⚠ For the value to persist, pass isManualOpportunity: true in the same request — otherwise Bitrix24 recalculates the amount from the product rows
isManualOpportunity boolean Manual amount mode (see opportunity)
currency string Currency (alias currencyId). List: GET /v1/currencies
companyTitle string Company name (text, not ID)
phone string | string[] | object[] Phone. Accepts three forms: a string "+1...", an array of strings ["+1...", "+1..."], or an array of objects [{ "value": "+1...", "typeId": "WORK" }, …]. typeId: WORK | HOME | MOBILE | OTHER (default WORK). ⚠ The UPPER form [{ "VALUE": "...", "VALUE_TYPE": "WORK" }] is not accepted — it returns 400 INVALID_MULTIFIELD_SHAPE. Use camelCase: [{ "value": "...", "typeId": "WORK" }]
email string | string[] | object[] Email. Accepts three forms: a string "a@b.com", an array of strings ["a@b.com", "b@c.com"], or an array of objects [{ "value": "a@b.com", "typeId": "WORK" }, …]. typeId: WORK | HOME | MAILING | OTHER (default WORK). ⚠ The UPPER form [{ "VALUE": "...", "VALUE_TYPE": "WORK" }] is not accepted — it returns 400 INVALID_MULTIFIELD_SHAPE. Use camelCase: [{ "value": "...", "typeId": "WORK" }]
post string Position
comments string Comment
sourceId string Source. List: GET /v1/statuses?filter[entityId]=SOURCE
sourceDescription string Source description
assignedById number Assignee. List: GET /v1/users
opened boolean Available to everyone

Full list of fields: GET /v1/leads/fields.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/leads \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Website request",
    "name": "Maria",
    "lastName": "Davis",
    "phone": "+12025550123",
    "sourceId": "WEB",
    "stageId": "NEW"
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/leads \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Website request",
    "name": "Maria",
    "lastName": "Davis",
    "phone": "+12025550124",
    "sourceId": "WEB",
    "stageId": "NEW"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/leads', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Website request',
    name: 'Maria',
    lastName: 'Davis',
    phone: '+12025550125',
    sourceId: 'WEB',
    stageId: 'NEW',
  }),
})

const { success, data } = await res.json()
console.log('Lead ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/leads', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Website request',
    name: 'Maria',
    lastName: 'Davis',
    phone: '+12025550126',
    sourceId: 'WEB',
    stageId: 'NEW',
  }),
})

const { success, data } = await res.json()

Alternative form — array of objects with explicit `typeId`

If you need to specify multiple values or an explicit type (HOME, MOBILE):

JSON 
{
  "phone": [
    { "value": "+12025550127", "typeId": "WORK" },
    { "value": "+12025550123", "typeId": "MOBILE" }
  ],
  "email": [
    { "value": "work@example.com", "typeId": "WORK" },
    { "value": "personal@example.com", "typeId": "HOME" }
  ]
}

Response fields

Field Type Description
id number ID of the created lead
title string Title
stageId string Lead status (stage)
assignedById number Assignee
createdBy number Creator
createdTime datetime Creation date

The response contains all lead fields.

The lead card URL in Bitrix24 is built from id:

https://<portal>.bitrix24.com/crm/lead/details/<id>/

<portal> — the Bitrix24 portal domain. Access is limited by the employee's permissions in Bitrix24.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 5001,
    "title": "Website request",
    "stageId": "NEW",
    "assignedById": 1,
    "createdBy": 1,
    "createdTime": "2026-04-15T13:00:00+00:00",
    "updatedTime": "2026-04-15T13:00:00+00:00",
    "opened": true,
    "sourceId": "WEB"
  }
}

Error response example

403 — no scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Errors

HTTP Code Description
403 SCOPE_DENIED The API key does not have the crm scope
401 TOKEN_MISSING The API key has no configured tokens
400 INVALID_MULTIFIELD_SHAPE Wrong shape for phone or email — expects [{ "value", "typeId" }]
400 READONLY_FIELD Attempt to write a read-only field

Full list of common API errors — Errors.

Known specifics

Simple CRM mode (no leads): when the Bitrix24 account runs CRM in simple mode, Bitrix24 converts the lead right on creation — it comes back CONVERTED and closed, with a contact and a deal created from it that the request never asked for. The requested stage is not kept. Vibecode changes nothing in the request: this is Bitrix24's own behaviour, and the mode cannot be switched through the API — only in the CRM settings. The response stays 201, and meta.warnings gets a LEAD_AUTO_CONVERTED warning with the ids of the contact (contactId) and deal (dealId) Bitrix24 created; null when the record was not created or not found: a contact you bound yourself via contactId is reused by Bitrix24 and does not count as created. There is no warning when CONVERTED was requested explicitly. On such an account, create deals and contacts directly.

Lead conversion: Bitrix24 REST has no dedicated conversion method. To "convert" a lead, create a deal/contact/company with leadId and update the lead status:

javascript 
// 1. Create a deal from the lead
await fetch('/v1/deals', { body: { title: 'From lead', leadId: 5001 } })
// 2. Close the lead
await fetch('/v1/leads/5001', { method: 'PATCH', body: { statusId: 'CONVERTED' } })

See also