## 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](/docs/entities/smart-processes/list). Use the built-in resource names for other types.

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `fieldId` | string | yes | Native non-empty CRM field identifier, for example `comments` or `opportunity`. See the naming rules below. |
| `categoryId` | integer | yes, except leads and quotes | Non-negative funnel ID from [deal categories](/docs/entities/deal-categories/list) or [categories](/docs/entities/categories/list). Bitrix24 checks whether it applies. |
| `requiredStageIds` | string[] | no | Omit for the entire funnel or global requirement. A non-empty list selects [stages](/docs/entities/statuses/list). `[]` clears the setting. |

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](/docs/userfields/crm) or [smart process user fields](/docs/userfields/smart-processes). 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

```bash
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

```bash
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

```javascript
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

```javascript
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

| Field | Type | Description |
|---|---|---|
| `success` | boolean | `true` |
| `data.fieldId` | string | Field identifier. |
| `data.categoryId` | integer or null | Funnel context, or null for a global setting. |
| `data.mode` | string | `none` — no setting; `all` — required throughout; `stages` — required at selected stages. |
| `data.requiredStageIds` | string[] | Required stages. |
| `data.globallyRequired` | boolean | Field is globally required by the platform. |

## Response example

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

## Error response example

400 — missing field identifier:

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

## Errors

| HTTP | Code | Description |
|---|---|---|
| 400 | `INVALID_PARAMS` | Malformed parameters or body. |
| 400 | `INVALID_FIELDS` | Unknown body field. |
| 400 | `UNKNOWN_FILTER_FIELD` | Unknown or misplaced query parameter. |
| 400 | `INVALID_ENTITY_TYPE` | Invalid smart process type. |
| 401 | `TOKEN_MISSING` | Missing portal credentials. |
| 403 | `SCOPE_DENIED` | Missing crm scope. |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Write through a read-only key. |
| 404 | Native Bitrix24 code | Field or context not found. |
| 409 | Native Bitrix24 code | Configuration conflict. |
| 422 | `METHOD_NOT_YET_AVAILABLE` | Feature is off or the method is unavailable. error.release identifies the release line. |
| 502 | `BITRIX_UNAVAILABLE` | Malformed upstream response. |

[Common errors](/docs/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](/docs/entities/crm-required-fields)