## 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 |
|----------|-----|:-----:|---------|
| `iblockId` (path) | string | yes | List identifier — numeric `IBLOCK_ID` or symbolic `IBLOCK_CODE`. List of lists: `GET /v1/lists` |

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|---------|
| `iblockTypeId` | string | no | Info block type. Values:<br>`lists` — regular lists, default<br>`lists_socnet` — workgroup lists<br>`bitrix_processes` — service workflows<br>`structure` — company-structure type (absence-calendar iblock `absence`) |
| `fields` | object | yes | Properties of the new field in Bitrix24 format (uppercase) |
| `fields.NAME` | string | yes | Field name |
| `fields.TYPE` | string | yes | Field type. Allowed values — [Field types](/docs/lists/fields/field-types) |
| `fields.CODE` | string | yes | Field symbolic code. Without it, the request fails with a `422 BITRIX_ERROR` response |
| `fields.IS_REQUIRED` | string | no | Whether the field is required: `Y` or `N` |
| `fields.MULTIPLE` | string | no | Multiple value: `Y` or `N` |
| `fields.SORT` | number | no | Position 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 |
| `fields.DEFAULT_VALUE` | string | no | Default value |

## Examples

### curl — personal key

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

```bash
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 |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data.id` | string | Identifier 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 |
|------|-----|---------|
| 400 | `INVALID_IBLOCK_TYPE` | `iblockTypeId` is not one of `lists`, `bitrix_processes`, `lists_socnet`, `structure` |
| 400 | `MISSING_REQUIRED_FIELDS` | The `fields` object is missing or lacks `NAME` / `TYPE` |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the creation. For example, `CODE` is not filled — message "Please fill the code fields" |
| 403 | `BITRIX_ACCESS_DENIED` | No permission to edit the list |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |
| 403 | `SCOPE_DENIED` | The key lacks 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](/docs/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](/docs/lists/fields/list) returns the current values.

## See also

- [Field types](/docs/lists/fields/field-types)
- [Update a field](/docs/lists/fields/update)
- [List fields](/docs/lists/fields)