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
iblockId (path) string yes List ID or symbolic code. List: GET /v1/lists

Request fields (body)

Field Type Required Description
elementCode string yes Symbolic code of the new row at the top level of the body, next to fields
fields object yes Row 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"]
iblockSectionId number no ID of the section to place the row in. The value 0 is the list root. List: GET /v1/lists/:iblockId/sections
listElementUrl string no Link to the row page
iblockTypeId string no Infoblock type. Values:
lists — regular lists, default
lists_socnet — workgroup lists
bitrix_processes — internal workflows

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
success boolean Always true on success
data.id number ID 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
400 MISSING_REQUIRED_FIELDS elementCode or fields is missing
400 INVALID_IBLOCK_TYPE iblockTypeId is not one of lists, bitrix_processes, lists_socnet
403 BITRIX_ACCESS_DENIED No permission to add rows to this list
403 WRITE_BLOCKED_READONLY_KEY The key is in read-only mode. Switch it to read and write in the /keys section
403 SCOPE_DENIED The key is missing the lists scope
401 TOKEN_MISSING The key has no configured tokens
409 LISTS_MODULE_NOT_ENABLED The Lists module is not enabled on the portal

Full list of common API errors — Errors.

See also