#Smart process item fields

GET /v1/items/:entityTypeId/fields

Returns the 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.

#Examples

In the examples entityTypeId = 156 — replace it with your smart process ID.

#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).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

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 platform docs shape. 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. The schema also declares binding fields like contacts (type crm_contact) — this is the input format for create/update. There are no such keys in list/get data; bindings are read via contactId / contactIds. System fields that Bitrix24 returns in list/get but that are not described above (taxValue, webformId, previousStageId, lastActivityBy, lastCommunication*, utm*) are passed through as-is.

#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 },
      "contacts": { "type": "crm_contact", "readonly": false, "label": "Contacts" },
      "ufCrm156_custom": { "type": "string", "readonly": false },
      "parentId156": { "type": "number", "readonly": false }
    }
  }
}

Fields arrive inside data.fields. The response object also contains data.products (the product rows schema), data.aggregatable (fields available in aggregation) and data.batch.

#Error response example

404 — not found:

{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Item not found"
  }
}

#Errors

Full list of common API errors — Errors.

#See also

• Create an item
• Item list
• Smart processes
• Entity API