Set a CRM field requirement

PUT /v1/deals/fields/required

Set whether a CRM field is required for everyone who edits or saves records in the Bitrix24 account.

Rolling out with crm 26.2000.0. Availability depends on the Bitrix24 account. A disabled feature or missing portal method returns 422 METHOD_NOT_YET_AVAILABLE with error.release. The release line alone does not guarantee that the method is enabled.

Scope crm. READWRITE is required.

Parameters

Resource variants:

PUT /v1/deals/fields/required

PUT /v1/leads/fields/required

PUT /v1/contacts/fields/required

PUT /v1/companies/fields/required

PUT /v1/quotes/fields/required

PUT /v1/invoices/fields/required

PUT /v1/items/:entityTypeId/fields/required

Smart process entityTypeId is a safe integer of at least 128, from smart processes. Use the built-in resource names for other types.

Request body

Use only a flat JSON body, without a fields wrapper or query parameters.

Leads and quotes do not accept categoryId. Other types require it. 0 selects the default category for deals, contacts and companies. Invoices and smart processes need an existing positive category ID. These rules are checked by Bitrix24.

Standard field identifiers use native CRM names. The amount field is opportunity, although the V1 entity API calls it amount. V1 aliases are not converted.

For a custom field, use the original UF_* value from fieldName in CRM user fields or smart process user fields. Smart invoices use /v1/userfields/invoices. Do not use the ufCrm... alias from the entity dictionary. Field identifiers are not converted.

Examples

curl — personal key

curl -X PUT "https://vibecode.bitrix24.com/v1/deals/fields/required" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fieldId": "comments", "categoryId": 0}'

curl — OAuth application

curl -X PUT "https://vibecode.bitrix24.com/v1/deals/fields/required" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fieldId": "comments", "categoryId": 0}'

JavaScript — personal key

const response = await fetch('https://vibecode.bitrix24.com/v1/deals/fields/required', {
  "method": "PUT",
  "headers": {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  "body": "{\"fieldId\": \"comments\", \"categoryId\": 0}"
})
const result = await response.json()
console.log(result)

JavaScript — OAuth application

const response = await fetch('https://vibecode.bitrix24.com/v1/deals/fields/required', {
  "method": "PUT",
  "headers": {
    "X-Api-Key": "YOUR_APP_KEY",
    "Authorization": "Bearer USER_SESSION_TOKEN",
    "Content-Type": "application/json"
  },
  "body": "{\"fieldId\": \"comments\", \"categoryId\": 0}"
})
const result = await response.json()
console.log(result)

Response fields

Response example

{
  "success": true,
  "data": {
    "fieldId": "comments",
    "categoryId": 0,
    "mode": "all",
    "requiredStageIds": [],
    "globallyRequired": false
  }
}

Error response example

400 — missing field identifier:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "fieldId must be a non-empty string"
  }
}

Errors

Common errors.

Known specifics

Clearing a setting does not override a system field that Bitrix24 makes globally required. Unknown fields and invalid stage or funnel combinations are rejected by Bitrix24 with its original code and message.

See also

• Required CRM fields