Required CRM fields

Read, set and clear the required property of one CRM field. Changes affect CRM cards and record saving for all users of the Bitrix24 account.

Bitrix24 API: crm.<entity>.field.required.{get,set,clear} Scope: crm

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.

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.

Read a CRM field requirement

GET /v1/deals/fields/required

Read the requirement setting for one CRM field in the selected funnel.

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. READONLY is allowed.

Parameters

Resource variants:

GET /v1/deals/fields/required

GET /v1/leads/fields/required

GET /v1/contacts/fields/required

GET /v1/companies/fields/required

GET /v1/quotes/fields/required

GET /v1/invoices/fields/required

GET /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.

Pass parameters in the query string. Send no body or Content-Type header.

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 GET "https://vibecode.bitrix24.com/v1/deals/fields/required?fieldId=comments&categoryId=0" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

curl -X GET "https://vibecode.bitrix24.com/v1/deals/fields/required?fieldId=comments&categoryId=0" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

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

JavaScript — OAuth application

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

Response fields

Response example

{
  "success": true,
  "data": {
    "fieldId": "comments",
    "categoryId": 0,
    "mode": "none",
    "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