## Smart process item fields

`GET /v1/items/:entityTypeId/fields`

Returns a description of all fields for the given smart process type, including user fields (`ufCrmN_*`) and parent references (`parentIdN`).

The field set depends on `entityTypeId` — each smart process type has its own user fields.

Use the `entityTypeId` field from [`GET /v1/smart-processes`](/docs/entities/smart-processes/list) in the `/v1/items/:entityTypeId` path. The type record's internal `id` is a different identifier. For example, if a type is returned as `{ "id": 3, "entityTypeId": 174 }`, the path starts with `/v1/items/174`. Use the returned value rather than assuming all type IDs start at 1030.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `entityTypeId` (path) | number | yes | Smart process type ID. List: [`GET /v1/smart-processes`](/docs/entities/smart-processes/list) |

## Examples

The examples use `entityTypeId = 156`; replace it with the ID of your smart process.

### curl — personal key

```bash
curl -X GET https://vibecode.bitrix24.com/v1/items/156/fields \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl -X GET https://vibecode.bitrix24.com/v1/items/156/fields \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/items/156/fields', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data } = await res.json()
console.log('Fields:', Object.keys(data.fields).length)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/items/156/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

## Response fields

The `label` and `description` values are returned in English, while those the platform takes straight from the Bitrix24 account come in the account language. Request headers do not switch the language.

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | object | The item field schema and the operations available for items of this smart process. Its keys are in the rows below |
| `data.fields` | object | The item field schema: field name → an object with `type`, `readonly`, `label` and `description`. Some fields also carry extra attributes such as `nullable`, `multiple` and `importable`. The standard fields are listed below, and the `ufCrmN_*` user fields and `parentIdN` parent references of this smart process are added to them |
| `data.products` | object | Operations on the item's product rows, the `setWarning` notice that `set` replaces all rows, and the product row field schema. See [Item product fields](/docs/entities/items/products-fields) |
| `data.aggregatable` | array | Standard fields allowed in the [aggregation](/docs/entities/items/aggregate) `groupBy`: `stageId`, `assignedById`, `categoryId`, `createdBy`, `updatedBy`. Numeric functions accept fields of type `number` |
| `data.batch` | array | Item write operations available in [batch calls](/docs/batch): `create`, `update`, `delete` |
| `data.import` | object | Method, path and maximum batch size for [importing records](/docs/import) |

### Standard item fields

| Field | Type | RO | Description |
|------|-----|:--:|---------|
| `id` | number | yes | Item ID |
| `title` | string | | Name |
| `xmlId` | string | | External code |
| `stageId` | string | | Stage. Format: `DT{typeId}_{catId}:{stage}` |
| `categoryId` | number | | Pipeline ID. List: `GET /v1/categories/:entityTypeId` |
| `assignedById` | number | | Responsible person. List: `GET /v1/users` |
| `companyId` | number | | Company ID. Search: `GET /v1/companies`. Requires the smart process to have the "Client" block enabled, otherwise `400 CLIENT_BLOCK_DISABLED` |
| `contactId` | number | | Contact ID. Search: `GET /v1/contacts`. Requires the smart process to have the "Client" block enabled, otherwise `400 CLIENT_BLOCK_DISABLED` |
| `contactIds` | array | | Linked contacts. Send the full list — it replaces the existing links instead of adding to them. Requires the smart process to have the "Client" block enabled, otherwise `400 CLIENT_BLOCK_DISABLED` |
| `opportunity` | number | | Amount. Stored only on types with product rows enabled (`isLinkWithProductsEnabled: true`); a request with an explicit `isManualOpportunity: true` on a type without them is refused with `422 AMOUNT_NOT_APPLIED` instead of a false success |
| `currencyId` | string | | Currency. List: `GET /v1/currencies` |
| `opened` | boolean | | Available to everyone |
| `begindate` | datetime | | Start date. Stored without time — the passed time is dropped |
| `closedate` | datetime | | Completion date. Stored without time — the passed time is dropped |
| `sourceId` | string | | Source |
| `sourceDescription` | string | | Free-form description of the source |
| `observers` | array | | Observers |
| `mycompanyId` | number | | Own company ID |
| `createdBy` | number | yes | Creator |
| `updatedBy` | number | yes | Last editor |
| `movedBy` | number | yes | Who moved the item to its current stage |
| `createdTime` | datetime | yes | Creation date |
| `updatedTime` | datetime | yes | Modification date |
| `movedTime` | datetime | yes | Stage change date |
| `isManualOpportunity` | boolean | | Amount set manually (`Y`/`N` → `true`/`false`). Stored only on types with product rows enabled (`isLinkWithProductsEnabled: true`); a request with an explicit `isManualOpportunity: true` on a type without them is refused with `422 AMOUNT_NOT_APPLIED` instead of a false success |
| `isRecurring` | boolean | yes | Recurring item flag |
| `lastActivityTime` | datetime | yes | Last activity time |
| `entityTypeId` | number | yes | Smart process type ID. Taken from the path segment, not accepted in the request body |
| `webformId` | number | yes | ID of the CRM form the item was created from. `0` — the item was not created through a form |
| `utmSource` | string \| null | yes | `utm_source` tag of the traffic source |
| `utmMedium` | string \| null | yes | `utm_medium` tag — the traffic channel, for example `cpc` or `email` |
| `utmCampaign` | string \| null | yes | `utm_campaign` tag — the advertising campaign name |
| `utmContent` | string \| null | yes | `utm_content` tag — the advertisement content or variant |
| `utmTerm` | string \| null | yes | `utm_term` tag — the advertisement keyword |

Bitrix24 returns the UTM fields in `list`/`get`, but for smart process items it does not accept them in the request body, in a filter or in sorting — hence the read-only mark, and a request with `filter[utmSource]` returns an error.

`isManualOpportunity` and `isRecurring` arrive from Bitrix24 as the string `"Y"`/`"N"` — the platform normalizes them to a JSON `boolean` on read (and accepts `true`/`false` on write for `isManualOpportunity`), just like `opened`.

User fields (`ufCrmN_*`) and parent references (`parentIdN`) depend on the specific smart process. For `enumeration`-type fields the response contains an `items` array with the available values.

> **Nullability.** Many fields arrive as `null` when not filled in — in particular `xmlId`, `sourceDescription`, `lastActivityTime` and the UTM fields (`utmSource`/`utmMedium`/`utmCampaign`/`utmContent`/`utmTerm`, if enabled on the Bitrix24 account). For type-safe clients (TS), declare such fields as `T | null`.

> **`/fields` reflects the live Bitrix24 contract, not the shape of the platform docs.** This is a passthrough of the Bitrix24 field schema as is: types arrive in Bitrix24 notation (`number`, `string`, `boolean`, `datetime`, `double`, `enumeration`, `crm_contact`, `crm_status`, `user` and others), the flag is `readonly` (not `isReadOnly`), some fields have a `label`, and there is no separate `isRequired` or `title`. Linked contacts are read and written through `contactId` and `contactIds`. The platform does **not** list the `contacts` service field of the Bitrix24 schema in this response: no value for it arrives in either list or get responses, and on write Bitrix24 accepts only an empty array — it rejects any non-empty value with an error from its own data layer. The field would be a promise with nothing behind it. System fields that Bitrix24 returns in list/get but that are not described above (`taxValue`, `previousStageId`, `lastActivityBy`, `lastCommunication*`) are passed through as-is. The fields in the table above are described by the platform itself, so they carry a human-readable `label` and `description`.

## Response example

```json
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true },
      "title": { "type": "string", "readonly": false },
      "stageId": { "type": "string", "readonly": false },
      "begindate": { "type": "datetime", "readonly": false },
      "ufCrm156_custom": { "type": "string", "readonly": false },
      "parentId156": { "type": "number", "readonly": false }
    }
  }
}
```

## Error response example

400 — the `entityTypeId` is reserved for a dedicated API:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_DYNAMIC_PARAM",
    "message": "entityTypeId 7 has a dedicated API: use /v1/quotes instead"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 403 | `SCOPE_DENIED` | The API key does not have the `crm` scope |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |
| 400 | `INVALID_DYNAMIC_PARAM` | `entityTypeId` is not a positive integer or is reserved (1, 2, 3, 4, 7, 31) |
| 429 | `RATE_LIMITED` | Rate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the `x-ratelimit-limit` header. Retry after the delay in the `Retry-After` header |

For the full list of common API errors, see [Errors](/docs/errors).

## See also

- [Create a smart process item](/docs/entities/items/create)
- [Item list](/docs/entities/items/list)
- [Smart processes](/docs/entities/smart-processes)
- [Entity API](/docs/entity-api)