For AI agents: markdown of this page — /docs-content-en/lists/fields/create.md documentation index — /llms.txt

Create a field

POST /v1/lists/:iblockId/fields

Creates a new field in a list. The field definition is passed in the fields object in Bitrix24 format — property names in uppercase.

Parameters

Parameter Type Required Description
ParameteriblockId (path) Typestring Requiredyes DescriptionList identifier — numeric IBLOCK_ID or symbolic IBLOCK_CODE. List of lists: GET /v1/lists

Request fields (body)

Field Type Required Description
FieldiblockTypeId Typestring Requiredno DescriptionInfo block type. Values:
lists — regular lists, default
lists_socnet — workgroup lists
bitrix_processes — service workflows
structure — company-structure type (absence-calendar iblock absence)
Fieldfields Typeobject Requiredyes DescriptionProperties of the new field in Bitrix24 format (uppercase)
Fieldfields.NAME Typestring Requiredyes DescriptionField name
Fieldfields.TYPE Typestring Requiredyes DescriptionField type. Allowed values — Field types
Fieldfields.CODE Typestring Requiredyes DescriptionField symbolic code. Without it, the request fails with a 422 BITRIX_ERROR response
Fieldfields.IS_REQUIRED Typestring Requiredno DescriptionWhether the field is required: Y or N
Fieldfields.MULTIPLE Typestring Requiredno DescriptionMultiple value: Y or N
Fieldfields.SORT Typenumber Requiredno DescriptionPosition of the new field in the card among the other list fields. After creation, the sort values of all fields are recalculated in increments of 10, so the stored value may differ from the one you pass
Fieldfields.DEFAULT_VALUE Typestring Requiredno DescriptionDefault value

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/lists/23/fields \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "NAME": "Status",
      "TYPE": "S",
      "CODE": "STATUS"
    }
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/lists/23/fields \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "NAME": "Status",
      "TYPE": "S",
      "CODE": "STATUS"
    }
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/lists/23/fields', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: {
      NAME: 'Status',
      TYPE: 'S',
      CODE: 'STATUS',
    },
  }),
})

const { success, data } = await res.json()
console.log('Field ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/lists/23/fields', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: {
      NAME: 'Status',
      TYPE: 'S',
      CODE: 'STATUS',
    },
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typestring DescriptionIdentifier of the created field in the format PROPERTY_<number>

Response example

JSON 
{
  "success": true,
  "data": {
    "id": "PROPERTY_1177"
  }
}

Error response example

422 — CODE not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Please fill the code fields"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_IBLOCK_TYPE DescriptioniblockTypeId is not one of lists, bitrix_processes, lists_socnet, structure
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe fields object is missing or lacks NAME / TYPE
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the creation. For example, CODE is not filled — message "Please fill the code fields"
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionNo permission to edit the list
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the lists scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens
HTTP409 CodeLISTS_MODULE_NOT_ENABLED DescriptionThe "Lists" module is not enabled on the portal

Full list of common API errors — Errors.

Known specifics

The field code is required on creation. A field is created only when CODE is passed in fields. Without it, the request fails with a 422 BITRIX_ERROR response and the message "Please fill the code fields", even though NAME and TYPE are filled.

Creating a field changes the SORT of the other fields. The value you pass only sets the position of the new field. After creation, all list fields, including the system NAME field, get the values 10, 20, 30 and so on in sort order. For example, if the fields have the values 10, 20, 30 and 40, a new field with SORT: 25 is stored with the value 30, and the fields with the values 30 and 40 get 40 and 50. List fields returns the current values.

See also