Update lead

PATCH /v1/leads/:id

Updates the fields of an existing lead. Pass only the fields you want to change. See the full list in the field reference.

Important note on email / phone (multifield): on update, phone and email only add rows. A PATCH with {"email": "new@y.com"} to a lead that already has an email will not replace the old one — the lead will end up with two emails. To change or delete a single row, send fm as an object keyed by the row id — see the section below. An object with an id field inside phone, email or fm[] is still refused: 400 MULTIFIELD_ID_NOT_SUPPORTED, and nothing is written.

Parameters

Request fields (body)

Examples

curl — personal key

curl -X PATCH "https://vibecode.bitrix24.com/v1/leads/42" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stageId": "IN_PROCESS",
    "opportunity": 2500,
    "isManualOpportunity": true,
    "assignedById": 3,
    "title": "Website request — hot lead"
  }'

curl — OAuth application

curl -X PATCH "https://vibecode.bitrix24.com/v1/leads/42" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stageId": "IN_PROCESS",
    "opportunity": 2500,
    "isManualOpportunity": true,
    "assignedById": 3,
    "title": "Website request — hot lead"
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/leads/42', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    stageId: 'IN_PROCESS',
    opportunity: 2500,
    isManualOpportunity: true,
    assignedById: 3,
    title: 'Website request — hot lead',
  }),
})

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

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/leads/42', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    stageId: 'IN_PROCESS',
    opportunity: 2500,
    isManualOpportunity: true,
    assignedById: 3,
    title: 'Website request — hot lead',
  }),
})

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):

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

Change or delete a single multifield row — `fm` keyed by row `id`

Send fm as an object. A key is a row id from fm in the GET response: a non-empty value changes that row, an empty value deletes it. A key n0, n1, … adds a new row. All three actions can be combined in one request.

{
  "fm": {
    "11": { "typeId": "PHONE", "valueType": "MOBILE", "value": "+14155550100" },
    "10": { "typeId": "EMAIL", "value": "" },
    "n0": { "typeId": "EMAIL", "valueType": "WORK", "value": "new@company.com" }
  }
}

• A row accepts only typeId, valueType and value. typeId is the channel: PHONE or EMAIL. valueType is required when a row changes: send the current one to keep it. A new row defaults to WORK, a deletion needs none.
• Before writing, Vibecode reads the lead and checks that every id is a row of this lead with the same typeId. Otherwise — 409 MULTIFIELD_ROW_NOT_FOUND, and nothing is written.
• After writing, the lead is read again: every changed row is compared with the requested value (a phone by its digits, an email case-insensitively), new rows by channel, subtype and value. Rows someone else added meanwhile do not spoil the comparison. If the change is not visible — 422 MULTIFIELD_NOT_APPLIED, with the re-read record in data. If it is visible but a row the request did not name is gone or changed — 200 with the MULTIFIELD_OTHER_ROWS_CHANGED warning in meta.warnings, with that row id in details.lostRows or details.changedRows. This happens when someone else edited the record meanwhile or Bitrix24 applied the write to that row too. If the re-read record carries fm in an unknown shape — 200 with the MULTIFIELD_UNVERIFIED warning in meta.warnings.
• If the row was deleted between the read and the write (the write waits for the account queue and for rate-limit repeats), Bitrix24 creates it again with the requested value: the answer is 422 MULTIFIELD_NOT_APPLIED, with the row id in error.details.keys.
• This form has not been checked on a self-hosted Bitrix24 account yet. If the CRM module applies it differently, the answer is 422 MULTIFIELD_NOT_APPLIED or the MULTIFIELD_OTHER_ROWS_CHANGED warning: the write has already happened, so compare the record in data before sending anything again.
• An fm object cannot be combined with phone and email in one request. An array in phone and email and fm[] still only add rows.
• This form is available only in this PATCH. Batch updates, import and create accept fm only as an array.

Response fields

Response example

{
  "success": true,
  "data": {
    "id": 42,
    "title": "Website request",
    "stageId": "IN_PROCESS",
    "assignedById": 1,
    "createdTime": "2026-04-15T12:00:00+00:00",
    "updatedTime": "2026-04-15T13:00:00+00:00"
  }
}

Error response example

404 — lead not found:

{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Item not found"
  }
}

Errors

Full list of common API errors — Errors.

See also

• Working with files in CRM fields
• Get lead
• Lead fields
• Statuses
• Batch
• Limits and optimization