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

Application line fields

GET /v1/telephony-lines/fields

Returns the field schema of an external application line: the type of each field, whether it is writable, its label and description. The schema is needed before adding and updating a line — it shows which fields are accepted and which are read-only.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/telephony-lines/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/telephony-lines/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

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

JavaScript — OAuth application

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

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.fields Typeobject DescriptionLine field schema. The key is the field name in camelCase, the value is its description
Fielddata.fields.<name>.type Typestring DescriptionField value type: string or boolean
Fielddata.fields.<name>.readonly Typeboolean Descriptiontrue — the field is read-only, and a write is rejected with 400 READONLY_FIELD
Fielddata.fields.<name>.nullable Typeboolean DescriptionPresent on fields that may arrive with a null value
Fielddata.fields.<name>.notReturned Typeboolean DescriptionPresent on fields that are declared in the schema but never come back in responses. Explicitly selecting such a name returns UNKNOWN_SELECT_FIELD
Fielddata.fields.<name>.label Typestring DescriptionShort field label
Fielddata.fields.<name>.description Typestring DescriptionExtended field description
Fielddata.batch Typearray DescriptionLine operations available in a batch call: create, update, delete

The schema describes four fields:

Field Type RO Description
Fieldnumber Typestring RO DescriptionExternal line number — also the line identifier in the update and delete paths
Fieldname Typestring | null RO DescriptionLine name shown in the interface. A line created without a name returns null
FieldcrmAutoCreate Typeboolean RO DescriptionWhether to auto-create a lead or a contact for calls on this line
FieldserverName Typestring ROyes DescriptionName of the telephony server the line is registered on. Not returned in responses, rejected on write

Response example

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "number": {
        "type": "string",
        "readonly": false,
        "label": "Line number",
        "description": "External line number — the identifier of the telephony line."
      },
      "serverName": {
        "type": "string",
        "readonly": true,
        "notReturned": true,
        "label": "Server name",
        "description": "Name of the telephony server the line is registered on. Read-only: Bitrix24 neither stores nor returns it, so a write is rejected with 400 READONLY_FIELD instead of being silently dropped."
      },
      "name": {
        "type": "string",
        "readonly": false,
        "nullable": true,
        "label": "Line name",
        "description": "Human-readable name of the line shown in the interface. Nullable: a line created without a name returns null here."
      },
      "crmAutoCreate": {
        "type": "boolean",
        "readonly": false,
        "label": "Auto-create CRM entities",
        "description": "Whether CRM entities (lead/contact) are created automatically for calls on this line."
      }
    },
    "batch": ["create", "update", "delete"]
  }
}

Error response example

401 — no key provided:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Errors

HTTP Code Description
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not provided
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens
HTTP401 CodeKEY_INACTIVE DescriptionThe API key is inactive or revoked
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the telephony scope
HTTP429 CodeRATE_LIMITED DescriptionRequest rate limit exceeded

Full list of common API errors — Errors.

Known specifics

The schema is the same on every Bitrix24 account. The response is assembled from the line description on the Vibecode side rather than requested from the account, so the set of fields and their types do not depend on a particular account's settings or on Bitrix24 availability. The response is cached, and the X-Cache header shows where it came from — the rules and the ways to bypass the cache are described in Limits and optimization.

serverName is declared but never comes back. The field is in the schema, marked notReturned, and this is not a desync: it never comes back in the list, create, or update responses, and an attempt to write a value is rejected with 400 READONLY_FIELD — the value is never silently lost. An explicit select=serverName returns an UNKNOWN_SELECT_FIELD warning, and the field is absent from the response. Treat it as a reference description, not as a data source.

batch names the available batch operations. The array lists the line operations accepted by a batch call: create, update, delete. Reads are not in this list — the list of lines is fetched by a separate call.

See also