Update company

PATCH /v1/companies/:id

Updates company fields. Pass only the fields you want to change. For the full list, see the field reference.

Important note on email / phone / web (multifield): on update, phone, email and web only add rows. A PATCH with {"email": "new@y.com"} to a company that already has an email will not replace the old one — the company 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, web or fm[] is still refused: 400 MULTIFIELD_ID_NOT_SUPPORTED, and nothing is written.

Frequently updated fields

Examples

curl — personal key

curl -X PATCH "https://vibecode.bitrix24.com/v1/companies/1" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Acme Inc. (updated)", "industry": "MANUFACTURING" }'

curl — OAuth application

curl -X PATCH "https://vibecode.bitrix24.com/v1/companies/1" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Acme Inc. (updated)", "industry": "MANUFACTURING" }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/companies/1', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ title: 'Acme Inc. (updated)', industry: 'MANUFACTURING' }),
})

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

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/companies/1', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ title: 'Acme Inc. (updated)', industry: 'MANUFACTURING' }),
})

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

Alternative form — array of objects with explicit `typeId`

If you need to specify several values or an explicit type (HOME, OTHER):

{
  "phone": [
    { "value": "+12025550123", "typeId": "WORK" },
    { "value": "+12025550124", "typeId": "OTHER" }
  ],
  "email": [
    { "value": "info@example.com", "typeId": "WORK" },
    { "value": "sales@example.com", "typeId": "MAILING" }
  ],
  "web": [
    { "value": "https://example.com", "typeId": "WORK" },
    { "value": "https://example.com", "typeId": "OTHER" }
  ]
}

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": "WEB", "valueType": "WORK", "value": "https://example.com" }
  }
}

• A row accepts only typeId, valueType and value. typeId is the channel: PHONE, EMAIL or WEB. 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 company and checks that every id is a row of this company with the same typeId. Otherwise — 409 MULTIFIELD_ROW_NOT_FOUND, and nothing is written.
• After writing, the company is read again: every changed row is compared with the requested value (a phone by its digits, an email case-insensitively, a website case-insensitively only in its scheme and host), 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, email and web in one request. An array in phone, email, web 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

The updated company object — see Company fields.

Response example

{
  "success": true,
  "data": {
    "id": 1,
    "title": "Acme Inc. (updated)",
    "industry": "MANUFACTURING",
    "assignedById": 1,
    "createdTime": "2020-05-08T10:48:20+00:00",
    "updatedTime": "2026-04-15T12:00:00+00:00"
  }
}

Error response example

404 — company 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 company
• Company fields
• Batch
• Limits and optimization