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

Create an enumeration field value

POST /v1/userfields/:entity/enum-values

Adds one option to an existing CRM enumeration field. Send the body without a fields wrapper.

This feature is rolling out. It requires a CRM update after 26.2200.0 and activation by an administrator. The release version has not been published. Until available, requests return 422 METHOD_NOT_YET_AVAILABLE with error.release.

For Smart Process Automation (SPA) fields, use the same contract at POST /v1/items/:entityTypeId/userfields/enum-values. Invoices are also available through entityTypeId=31.

Parameters

Parameter Type Required Default Description
Parameterentity (path) Typestring Requiredyes Default— Descriptiondeals — deals, leads — leads, contacts — contacts, companies — companies, quotes — estimates, invoices — invoices
ParameterentityTypeId (path) Typeinteger Requiredfor the alternate path Default— DescriptionSPA type ID, or 31 for invoices

Request body fields

Field Type Required Description
FieldfieldId Typeinteger / string Requiredyes DescriptionID or UF_* code of an enumeration field. Sources: CRM fields, SPA fields
Fieldvalue Typestring Requiredyes DescriptionOption label
FieldisDefault Typeboolean Requiredno DescriptionUse as a default option
Fieldsort Typeinteger Requiredno DescriptionSort order
FieldxmlId Typestring / null Requiredno DescriptionExternal integration ID

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/userfields/deals/enum-values" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fieldId": 6008145, "value": "VIBE-PROBE option", "isDefault": false, "sort": 500, "xmlId": "VIBE-PROBE-X"}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/userfields/deals/enum-values" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fieldId": 6008145, "value": "VIBE-PROBE option", "isDefault": false, "sort": 500, "xmlId": "VIBE-PROBE-X"}'

JavaScript — personal key

javascript 
const response = await fetch(
  'https://vibecode.bitrix24.com/v1/userfields/deals/enum-values',
  {
    "method": "POST",
    "headers": {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "fieldId": 6008145,
      "value": "VIBE-PROBE option",
      "isDefault": false,
      "sort": 500,
      "xmlId": "VIBE-PROBE-X"
    })
  }
)
const { success, data } = await response.json()

JavaScript — OAuth application

javascript 
const response = await fetch(
  'https://vibecode.bitrix24.com/v1/userfields/deals/enum-values',
  {
    "method": "POST",
    "headers": {
      "X-Api-Key": "YOUR_APP_KEY",
      "Authorization": "Bearer USER_SESSION_TOKEN",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "fieldId": 6008145,
      "value": "VIBE-PROBE option",
      "isDefault": false,
      "sort": 500,
      "xmlId": "VIBE-PROBE-X"
    })
  }
)
const { success, data } = await response.json()

Response fields

HTTP 201 Created.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeobject DescriptionField option
Fielddata.id Typeinteger DescriptionOption ID for retrieval
Fielddata.fieldId Typeinteger DescriptionField ID. See CRM fields and SPA fields
Fielddata.value Typestring DescriptionOption label
Fielddata.isDefault Typeboolean DescriptionUsed as a default option
Fielddata.sort Typeinteger DescriptionSort order
Fielddata.xmlId Typestring / null DescriptionExternal integration ID

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 4119,
    "fieldId": 6008145,
    "value": "VIBE-PROBE option",
    "isDefault": false,
    "sort": 500,
    "xmlId": "VIBE-PROBE-X"
  }
}

Error response example

400 — invalid request:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Use enum fields fieldId (add only), value, isDefault, sort and xmlId with their documented types"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionInvalid request shape or parameter type
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionUnknown or repeated query parameter
HTTP422 CodeMETHOD_NOT_YET_AVAILABLE DescriptionThe feature is not yet available. Update information is provided in error.release
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionInvalid response from Bitrix24
HTTP401 CodeMISSING_API_KEY DescriptionMissing X-Api-Key
HTTP401 CodeTOKEN_MISSING DescriptionNo Bitrix24 tokens are configured
HTTP403 CodeSCOPE_DENIED DescriptionThe key requires the crm scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionCreation is blocked for a READONLY key

For shared API errors, see Errors.

Known specifics

After an ambiguous failure, check the option list before retrying. A blind retry can create another option.

See also