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

Create an element

POST /v1/lists/:iblockId/elements

Creates a new row in a list. Field values are passed inside the fields wrapper, while the symbolic code of the new row is passed as the elementCode parameter at the top level of the body, next to fields, not inside it.

Parameters

Parameter Type Required Description
ParameteriblockId (path) Typestring Requiredyes DescriptionList ID or symbolic code. List: GET /v1/lists

Request fields (body)

Field Type Required Description
FieldelementCode Typestring Requiredyes DescriptionSymbolic code of the new row at the top level of the body, next to fields
Fieldfields Typeobject Requiredyes DescriptionRow field values. System fields are named in uppercase, for example NAME. A custom property is set with the key PROPERTY_<id>, where <id> is the field identifier from GET /v1/lists/:iblockId/fields. A multiple-value property is passed as an array: "PROPERTY_951": ["1", "2"]
FieldiblockSectionId Typenumber Requiredno DescriptionID of the section to place the row in. The value 0 is the list root. List: GET /v1/lists/:iblockId/sections
FieldlistElementUrl Typestring Requiredno DescriptionLink to the row page
FieldiblockTypeId Typestring Requiredno DescriptionInfoblock type. Values:
lists — regular lists, default
lists_socnet — workgroup lists
bitrix_processes — internal workflows
structure — company-structure type (holds the built-in absence-calendar iblock absence)

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/lists/23/elements \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "elementCode": "row_1",
    "fields": {
      "NAME": "Row 1",
      "PROPERTY_951": "value"
    }
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/lists/23/elements \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "elementCode": "row_1",
    "fields": {
      "NAME": "Row 1",
      "PROPERTY_951": "value"
    }
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/lists/23/elements', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    elementCode: 'row_1',
    fields: {
      NAME: 'Row 1',
      PROPERTY_951: 'value',
    },
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/lists/23/elements', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    elementCode: 'row_1',
    fields: {
      NAME: 'Row 1',
      PROPERTY_951: 'value',
    },
  }),
})

const { data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typenumber DescriptionID of the created row. Used as :elementId in GET, PATCH, DELETE

Response example

HTTP status 201 Created.

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

Error response example

400 — a required body parameter is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "`elementCode` is required (the symbolic code of the new element)."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionelementCode or fields is missing
HTTP400 CodeINVALID_IBLOCK_TYPE DescriptioniblockTypeId is not one of lists, bitrix_processes, lists_socnet, structure
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionNo permission to add rows to this list
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode. Open the path from error.details.switchUrl: a personal key points to /keys, an application key with a card to /applications, a standalone OAuth key to /apps, and a management key to /management-keys. Switch it to read and write there
HTTP403 CodeSCOPE_DENIED DescriptionThe key is missing 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 Bitrix24 portal
HTTP413 CodePAYLOAD_TOO_LARGE DescriptionThe request body is over 40 MiB. Nothing was written
HTTP429 CodeLARGE_BODY_BACKEND_BUSY DescriptionThe platform is already processing its maximum volume of request bodies over 1 MiB. Nothing was written, retry after Retry-After seconds

Full list of common API errors — Errors.

Known specifics

File size in a property. The value of a "File" property is passed inside fields as base64, and the request body is capped at 40 MiB — enough for an original file of just under 30 MiB. A batch call to POST /v1/batch keeps the 1 MiB cap, so send a large file with a single call to this method.

Activity flag. ACTIVE in fields is ignored: the row is created active even with "ACTIVE": "N", and the response still reports success.

See also