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

Examples

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

curl — personal key

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

curl — OAuth application

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

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

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.

Standard item fields

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

{
  "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:

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

Errors

For the full list of common API errors, see Errors.

See also

• Create a smart process item
• Item list
• Smart processes
• Entity API