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
success boolean Always true on success
data.fields object Line field schema. The key is the field name in camelCase, the value is its description
data.fields.<name>.type string Field value type: string or boolean
data.fields.<name>.readonly boolean true — the field is read-only, and a write is rejected with 400 READONLY_FIELD
data.fields.<name>.nullable boolean Present on fields that may arrive with a null value
data.fields.<name>.notReturned boolean Present on fields that are declared in the schema but never come back in responses. Explicitly selecting such a name returns UNKNOWN_SELECT_FIELD
data.fields.<name>.label string Short field label
data.fields.<name>.description string Extended field description
data.batch array Line operations available in a batch call: create, update, delete

The schema describes four fields:

Field Type RO Description
number string External line number — also the line identifier in the update and delete paths
name string | null Line name shown in the interface. A line created without a name returns null
crmAutoCreate boolean Whether to auto-create a lead or a contact for calls on this line
serverName string yes Name 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
401 MISSING_API_KEY The X-Api-Key header was not provided
401 INVALID_API_KEY Invalid API key
401 TOKEN_MISSING The key has no configured tokens
401 KEY_INACTIVE The API key is inactive or revoked
403 SCOPE_DENIED The key lacks the telephony scope
429 RATE_LIMITED Request 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