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

CRM field values and primary contact

Change one value without replacing the whole list, or choose an existing bound contact as primary.

Bitrix24 API: crm.<entity>.addfieldvalue, crm.<entity>.deletefieldvalue, crm.<entity>.setprimarycontact Scope: crm

These operations require the crm-rest-v3 flag and a Bitrix24 update after crm 26.2200.0 with RestV3CrudDeal enabled. Until available, calls return 422 METHOD_NOT_YET_AVAILABLE with error.release.

Add one CRM field value

POST /v1/deals/:id/fields/:field/values

POST /v1/leads/:id/fields/:field/values

POST /v1/contacts/:id/fields/:field/values

POST /v1/companies/:id/fields/:field/values

POST /v1/quotes/:id/fields/:field/values

POST /v1/invoices/:id/fields/:field/values

POST /v1/items/:entityTypeId/:id/fields/:field/values

Add one value to a field that supports multiple values.

These operations require the crm-rest-v3 flag and a Bitrix24 update after crm 26.2200.0 with RestV3CrudDeal enabled. Until available, calls return 422 METHOD_NOT_YET_AVAILABLE with error.release.

Requires crm scope and READWRITE access. Resource and value formats.

Parameters

Parameter Type Required Default Description
Parameterid (path) Typeinteger Requiredyes Default— DescriptionRecord ID from the corresponding list resource
ParameterentityTypeId (path) Typeinteger Requiredfor items Default— DescriptionSmart-process type from List smart process types
Parameterfield (path) Typestring Requiredyes Default— DescriptionExact REST v3 field name
ParameterisMyCompany (query) Typeboolean Requiredno Defaultfalse DescriptionOnly for companies: select own-company operations

Request body

Field Type Required Description
Fieldvalue TypeJSON Requiredyes DescriptionOne value in the native field format; Bitrix24 validates it

Examples

curl — personal key

Terminal 
curl -i -X POST "https://vibecode.bitrix24.com/v1/contacts/12/fields/email/values" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value":{"valueTypeId":"WORK","value":"vibe-probe@example.com"}}'

curl — OAuth application

Terminal 
curl -i -X POST "https://vibecode.bitrix24.com/v1/contacts/12/fields/email/values" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value":{"valueTypeId":"WORK","value":"vibe-probe@example.com"}}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/contacts/12/fields/email/values', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({"value": {"valueTypeId": "WORK", "value": "vibe-probe@example.com"}})
})
console.log(res.status === 204)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/contacts/12/fields/email/values', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Content-Type': 'application/json', 'Authorization': 'Bearer USER_SESSION_TOKEN' },
  body: JSON.stringify({"value": {"valueTypeId": "WORK", "value": "vibe-probe@example.com"}})
})
console.log(res.status === 204)

Response fields

Success is HTTP 204 No Content with an empty body. Check the status, do not parse JSON.

Response example

http 
HTTP/1.1 204 No Content

Error response example

400 — missing request field.

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Body must contain only value"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionInvalid request shape or ID
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionUnknown query parameter
HTTP400 CodeINVALID_ENTITY_TYPE_ID DescriptionReserved type requires its named resource
HTTP401 CodeTOKEN_MISSING DescriptionBitrix24 credentials are missing
HTTP403 CodeSCOPE_DENIED DescriptionKey lacks crm scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionKey forbids writes
HTTP404 CodeENTITY_NOT_FOUND DescriptionRecord was not found
HTTP422 CodeMETHOD_NOT_YET_AVAILABLE DescriptionFeature unavailable; error.release identifies the update
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionNo valid update confirmation

Bitrix24 failures use standard V1 error handling; messages are sanitized to remove credentials. Common errors.

See also