For AI agents: markdown of this page — /docs-content-en/entities/leads/fields.md documentation index — /llms.txt

Lead fields

GET /v1/leads/fields

Returns the full list of available fields, including user fields (ufCrm*).

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/leads/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/leads/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/leads/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/leads/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 field captions are returned in English, while the ones the platform takes straight from the Bitrix24 account come in the account language. Request headers do not switch the language.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe lead field schema and the operations available for leads. Its keys are in the rows below
Fielddata.fields Typeobject DescriptionThe lead field schema: field name → an object with type, readonly and label. Some fields also carry description and extra attributes such as nullable, multiple, enum and items. The standard fields are listed below, and the ufCrm* user fields of this Bitrix24 account are added to them
Fielddata.relations Typeobject DescriptionRelations: contact is the primary contact, company is the lead's company, contactBinding covers all linked contacts and the operations on them. See Lead contacts
Fielddata.products Typeobject DescriptionOperations on the lead's product rows, the setWarning notice that set replaces all rows, and the product row field schema. See Lead product fields
Fielddata.activities Typeobject DescriptionLead activities: the list and create operations and the call, meeting, email and task activity types. See Activities of a CRM record and Create an activity for a CRM record
Fielddata.actions Typeobject DescriptionActions on a lead: move gives the method, path and parameters for moving the lead to another status. See Move lead to another status
Fielddata.aggregatable Typearray DescriptionStandard fields allowed in the aggregation groupBy: stageId, statusId, opportunity, amount, sourceId, assignedById
Fielddata.batch Typearray DescriptionLead write operations available in batch calls: create, update, delete
Fielddata.import Typeobject DescriptionMethod, path and maximum batch size for importing records
Fielddata.include Typearray DescriptionThe names the include parameter accepts: contact, company, contactBinding

Standard lead fields

Field Type RO Description
Fieldid Typenumber ROyes DescriptionLead ID
Fieldtitle Typestring RO DescriptionLead title
Fieldname Typestring RO DescriptionFirst name
FieldlastName Typestring RO DescriptionLast name
FieldsecondName Typestring RO DescriptionMiddle name
FieldstageId Typestring RO DescriptionLead status (stage) — canonical name in responses: NEW, IN_PROCESS, … List: GET /v1/statuses?filter[entityId]=STATUS
FieldstatusId Typestring RO DescriptionWrite/filter/sort alias of stageId. Important: In list/get/search responses, the value is returned in the stageId field and the statusId key is not returned — read stageId. Do not pass both the alias and the canonical name in one request
FieldstageSemanticId Typestring ROyes DescriptionStage semantic category: P — in progress, S — success, F — failure. Read-only; accepted in filters and sorting
FieldcompanyTitle Typestring RO DescriptionCompany name
FieldcompanyId Typenumber RO DescriptionCompany ID. Lookup: GET /v1/companies
FieldcontactId Typenumber RO DescriptionContact ID. Lookup: GET /v1/contacts
Fieldopportunity Typenumber RO DescriptionAmount — canonical name in responses. Important: For the written value to persist, pass isManualOpportunity: true in the same request
Fieldamount Typenumber RO DescriptionWrite/filter alias of opportunity. In responses, the value is returned in the opportunity field
FieldisManualOpportunity Typeboolean RO DescriptionManual amount mode. Without true, the amount is recalculated from the product rows and the written value is overwritten
Fieldcurrency Typestring RO DescriptionWrite/filter alias of currencyId. Currency. List: GET /v1/currencies
FieldcurrencyId Typestring RO DescriptionCurrency — canonical name in responses
FieldsourceId Typestring RO DescriptionSource. List: GET /v1/statuses?filter[entityId]=SOURCE
FieldsourceDescription Typestring RO DescriptionSource description
FieldassignedById Typenumber RO DescriptionAssignee. List: GET /v1/users
FieldcreatedBy Typenumber ROyes DescriptionCreator. Lookup: GET /v1/users
Fieldopened Typeboolean RO DescriptionAvailable to everyone
Fieldcomments Typestring RO DescriptionComment
Fieldpost Typestring RO DescriptionPosition
Fieldphone Typemultifield RO DescriptionPhone. On input (POST/PATCH) accepts string | string[] | object[]. On output phone is a string with the primary value, per-type values are in phoneWork/phoneMobile, and the full list with types is in the fm[] array (format { id, typeId, valueType, value }). Important: PATCH only adds new records — old phone entries are not removed. See Update lead. Important: The UPPER form [{ "VALUE": "...", "VALUE_TYPE": "WORK" }] is not accepted — it returns 400 INVALID_MULTIFIELD_SHAPE. Use camelCase: [{ "value": "...", "typeId": "WORK" }]. An object with an id field is not accepted by any write operation — 400 MULTIFIELD_ID_NOT_SUPPORTED, and nothing is written. The same applies to a row with id inside the raw fm[] array. An object keyed by row ids ({"11": {…}}) is not accepted either — same code. An object without value — empty or with keys such as n0, 0 or 011 — and a number or true/false, on their own or as an array item, are refused with 400 INVALID_MULTIFIELD_SHAPE.
Fieldemail Typemultifield RO DescriptionEmail. On input accepts string | string[] | object[]. On output email is a string with the primary value, per-type values are in emailWork/emailHome/emailMailing, and the full list is in the fm[] array. Important: PATCH only adds new records — old email entries are not removed. Important: The UPPER form [{ "VALUE": "...", "VALUE_TYPE": "WORK" }] is not accepted — it returns 400 INVALID_MULTIFIELD_SHAPE. Use camelCase: [{ "value": "...", "typeId": "WORK" }]. An object with an id field is not accepted by any write operation — 400 MULTIFIELD_ID_NOT_SUPPORTED, and nothing is written. The same applies to a row with id inside the raw fm[] array. An object keyed by row ids ({"11": {…}}) is not accepted either — same code. An object without value — empty or with keys such as n0, 0 or 011 — and a number or true/false, on their own or as an array item, are refused with 400 INVALID_MULTIFIELD_SHAPE.
Fieldbirthdate Typedatetime RO DescriptionBirth date
FieldhasPhone Typeboolean ROyes DescriptionWhether a phone is set
FieldhasEmail Typeboolean ROyes DescriptionWhether an email is set
FieldhasImol Typeboolean ROyes DescriptionWhether there is an Open Channel contact
FieldisReturnCustomer Typeboolean ROyes DescriptionRepeat customer
FieldcreatedTime Typedatetime ROyes DescriptionCreation date
FieldupdatedTime Typedatetime ROyes DescriptionModification date
FieldoriginatorId Typestring RO DescriptionExternal source — identifier of the external system the lead was imported from; null for leads created in Bitrix24
FielddateClosed Typedatetime ROyes DescriptionDate the lead was closed; null while the lead is open
FieldlastCommunicationTime Typestring ROyes DescriptionDate of the last communication with the lead; null if there was none
FieldutmSource Typestring RO Descriptionutm_source tag of the traffic source; null if not set
FieldutmMedium Typestring RO Descriptionutm_medium tag of the traffic source; null if not set
FieldutmCampaign Typestring RO Descriptionutm_campaign tag of the traffic source; null if not set
FieldutmContent Typestring RO Descriptionutm_content tag of the traffic source; null if not set
FieldutmTerm Typestring RO Descriptionutm_term tag of the traffic source; null if not set

The UTM fields are returned in list/get but accepted neither in filter nor in sorting. A request with filter[utmSource] returns 400 UNKNOWN_FILTER_FIELD; a request with sort=utmSource returns 400 UNKNOWN_SORT_FIELD. Both requests are rejected before Bitrix24 is called.

User fields (ufCrm*) are also returned in responses and accepted on create/update. For an enumeration field, this endpoint returns an array of options at data.fields.<field name>.items, shaped as { "ID": "3977", "VALUE": "warm" }. This is not the enum key of declared fields with value and label elements: to write to a user field, send the ID, while VALUE is the option label for display. A label sent instead of the identifier is silently discarded. Details — Value format by type.

Response example

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true, "label": "ID", "description": "Unique numeric identifier of the lead." },
      "title": { "type": "string", "readonly": false, "label": "Title", "description": "Lead title." },
      "stageSemanticId": { "type": "string", "readonly": true, "label": "Stage semantics", "description": "Semantic category of the current stage — codes are decoded in enum.", "enum": [{ "value": "P", "label": "In progress" }, { "value": "S", "label": "Success" }, { "value": "F", "label": "Failure" }] },
      "assignedById": { "type": "number", "readonly": false, "label": "Assignee", "description": "ID of the responsible user. List: GET /v1/users." }
    },
    "relations": {
      "contact": { "type": "one", "entity": "contacts", "includable": true },
      "company": { "type": "one", "entity": "companies", "includable": true },
      "contactBinding": { "type": "many", "entity": "contacts", "operations": ["list", "add", "remove", "set", "clear"] }
    },
    "activities": { "operations": ["list", "create"], "types": ["call", "meeting", "email", "task"] },
    "actions": {
      "move": { "description": "Change lead status", "method": "POST", "path": "/v1/leads/{id}/move", "params": { "statusId": { "type": "string", "required": false }, "stageId": { "type": "string", "required": true } } }
    },
    "aggregatable": ["stageId", "statusId", "opportunity", "amount", "sourceId", "assignedById"],
    "batch": ["create", "update", "delete"],
    "import": { "method": "POST", "path": "/v1/leads/import", "maxItems": 100 },
    "include": ["contact", "company", "contactBinding"]
  }
}

Four fields from data.fields are shown, along with the other data keys. The data.products block is omitted from the example, and the full set of fields is in the tables above.

What to do with the names from data.include is covered on the Get lead page. More about the include parameter — Related data.

Error response example

403 — the key lacks the crm scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope",
    "hint": "This request needs the 'crm' scope, which the calling key does not carry. Add 'crm' to this key in the developer cabinet (or through the management API), then repeat the call.",
    "cause": "key_scope_missing",
    "requiredScope": "crm",
    "keyScopes": ["task", "im"],
    "fix": { "action": "edit_key_scopes", "via": "cabinet" },
    "userMessage": "The app's API key lacks the “CRM” permission. You can add it in the key settings in the developer cabinet."
  }
}

Errors

HTTP Code Description
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRate 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.

See also