For AI agents: markdown of this page — /docs-content-en/entities/contacts/update.md documentation index — /llms.txt

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.

Frequently updated fields

Parameter Type Description
Parametername Typestring DescriptionFirst name, at most 50 Unicode code points. Longer values are rejected before writing; the name is not truncated.
Parameterphone Typestring | string[] | object[] DescriptionPhone. 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). Important: the UPPER form [{ "VALUE": "...", "VALUE_TYPE": "WORK" }] is not accepted — it returns 400 INVALID_MULTIFIELD_SHAPE. Use camelCase: [{ "value": "...", "typeId": "WORK" }]
Parameteremail Typestring | string[] | object[] DescriptionEmail. 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). Important: the UPPER form [{ "VALUE": "...", "VALUE_TYPE": "WORK" }] is not accepted — it returns 400 INVALID_MULTIFIELD_SHAPE. Use camelCase: [{ "value": "...", "typeId": "WORK" }]
ParametercompanyId Typenumber DescriptionCompany ID. Lookup: GET /v1/companies
ParameterassignedById Typenumber DescriptionAssigned user. List: GET /v1/users
Parameterpost Typestring DescriptionPosition
ParameterufCrm* Typeper field schema DescriptionA user field of the Bitrix24 account, for example ufCrmProjectCode. The actual name and type are in the schema GET /v1/contacts/fields, and the value format for each type is in User fields (UF). An enumeration field takes the option ID from the field's items array in the schema, and a multiple field takes an array of such IDs. If you send the option label VALUE instead of the ID, the value is lost: a single-value field gets 0. A number that is not among the options is stored as is. Neither the label nor a non-existent ID raises an error, and the request returns 200, so map the label to its ID on your side and check the stored value of this field in the response data

Examples

curl — personal key

Terminal 
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

Terminal 
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

javascript 
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

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

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
Fielddata Typeobject DescriptionUpdated contact object with all fields — see Fields

The updated contact object — see Contact fields.

Response example

JSON 
{
  "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:

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

Errors

HTTP Code Description
HTTP404 CodeENTITY_NOT_FOUND DescriptionContact not found
HTTP403 CodeACCESS_DENIED DescriptionNo access
HTTP400 CodeINVALID_REQUEST DescriptionInvalid fields
HTTP400 CodeREADONLY_FIELD DescriptionThe request body contains a read-only field, such as phoneMobile. Such fields are marked in the RO column of Contact fields
HTTP400 CodeMULTIFIELD_ID_NOT_SUPPORTED Descriptionphone, email or the raw fm[] contains an object with an id field. Bitrix24 neither updates nor deletes a single multifield row through this call — it would append a duplicate — so the request is refused and nothing is written
HTTP403 CodeSCOPE_DENIED DescriptionAPI key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionAPI key has no configured tokens

Full list of common API errors — Errors.

See also