Update contact

PATCH /v1/contacts/:id

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

Important note on email / phone (multifield): On update, Bitrix24 only adds new multifield records. A PATCH with {"email": "new@y.com"} to a contact that already has an email will not replace the old one — the contact will end up with two emails. This is Bitrix24-specific behavior, not Vibecode's. To replace or remove an email/phone, edit the contact in the Bitrix24 UI. An object with an id field (an attempt to update or delete a single row) is not accepted by this PATCH: 400 MULTIFIELD_ID_NOT_SUPPORTED, and nothing is written. An object keyed by row ids ({"fm": {"11": {…}}}, or the same shape in phone/email) is refused as well: 400 MULTIFIELD_ID_NOT_SUPPORTED. The raw fm is accepted only as an array.

Parameters

Frequently updated fields

Examples

curl — personal key

curl -X PATCH "https://vibecode.bitrix24.com/v1/contacts/71" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+12025550123",
    "post": "Director"
  }'

curl — OAuth application

curl -X PATCH "https://vibecode.bitrix24.com/v1/contacts/71" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+12025550124",
    "post": "Director"
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/contacts/71', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone: '+12025550125',
    post: 'Director',
  }),
})

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

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/contacts/71', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone: '+12025550126',
    post: 'Director',
  }),
})

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": "+12025550127", "typeId": "WORK" },
    { "value": "+12025550123", "typeId": "MOBILE" }
  ],
  "email": [
    { "value": "work@example.com", "typeId": "WORK" },
    { "value": "personal@example.com", "typeId": "HOME" }
  ]
}

Response fields

The updated contact object — see Contact fields.

Response example

{
  "success": true,
  "data": {
    "id": 71,
    "name": "John",
    "lastName": "Brown",
    "companyId": 15,
    "assignedById": 1,
    "createdTime": "2020-05-08T10:48:20+00:00",
    "updatedTime": "2026-04-15T12:00:00+00:00"
  }
}

Error response example

404 — contact not found:

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

Errors

Full list of common API errors — Errors.

Known specifics

• A contact without a first and last name is not updated. If both name and lastName of an existing contact are empty, the update is refused even when the request changes other fields only, such as post. To update such a contact, send name or lastName in the same request. In a bulk update via POST /v1/contacts/batch, the item for such a contact gets success: false and error set to CRM_FIELD_ERROR_REQUIRED.

See also

• Working with files in CRM fields
• Get contact
• Contact fields
• Batch
• Limits and optimization