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

Search application lines

POST /v1/telephony-lines/search

Returns the external lines added by the application, taking its input from the request body instead of the query string. The whole collection of lines arrives in a single page.

The same set of lines is returned by GET /v1/telephony-lines.

Request fields (body)

Field Type Required Default Description
Fieldlimit Typenumber Requiredno Default50 DescriptionNumber of records, up to 5000
Fieldselect Typestring[] Requiredno Default— DescriptionField selection in camelCase: ["number", "name"]
Fieldfilter Typeobject Requiredno Default— DescriptionOnly an empty object {} is accepted: filtering by line fields is not supported, and any key inside returns 400 UNSUPPORTED_FILTER
FieldwithTotal Typeboolean Requiredno Default— DescriptionHas no effect on the response for application lines: meta.total is returned even with withTotal: false

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/telephony-lines/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 3 }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/telephony-lines/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 3 }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/telephony-lines/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ limit: 3 }),
})

const { success, data, meta } = await res.json()
console.log(`Found ${meta.total} lines`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/telephony-lines/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ limit: 3 }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of application lines. Empty until the application adds a line via POST /v1/telephony-lines
Fielddata[].number Typestring DescriptionLine identifier set at creation
Fielddata[].name Typestring | null DescriptionDisplay name. null if it was not set at creation
Fielddata[].crmAutoCreate Typeboolean DescriptionAuto-create a CRM entity on an outbound call through this line: true — create, false — do not create
Fieldmeta.total Typenumber DescriptionNumber of application lines
Fieldmeta.hasMore Typeboolean DescriptionWhether more records exist beyond limit
Fieldmeta.durationMs Typenumber DescriptionRequest duration in milliseconds

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "number": "sip-line-1",
      "name": "Main line",
      "crmAutoCreate": true
    },
    {
      "number": "sip-line-2",
      "name": "Support line",
      "crmAutoCreate": false
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false,
    "durationMs": 62
  }
}

Error response example

400 — a non-zero offset was passed:

JSON 
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_OFFSET",
    "message": "Entity 'telephony-lines' does not support offset — B24 method \"telephony.externalLine.get\" has no pagination and returns the full collection in one page. Remove offset and window the result on your side; limit still applies."
  }
}

Errors

HTTP Code Description
HTTP400 CodeUNSUPPORTED_OFFSET DescriptionA non-zero offset was passed — application lines do not support pagination
HTTP400 CodeUNSUPPORTED_FILTER DescriptionA filter was passed — filtering by line fields is not supported
HTTP400 CodeINVALID_SORT_FIELD DescriptionA sort or order was passed — sorting is not supported
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 API key has no configured tokens
HTTP401 CodeKEY_INACTIVE DescriptionThe API key is inactive or revoked
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the telephony scope
HTTP429 CodeRATE_LIMITED DescriptionRequest rate limit exceeded
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is temporarily unavailable — retry the request later

Full list of common API errors — Errors.

Known specifics

Switching to POST adds no filtering criteria. The body of this request accepts the same minimal set of parameters as the query string of the list endpoint. Find the line you need in the returned array by number on your side.

The record key is number; a line has no id field. Even when number is not named in select, it stays in every record of the response: without it a record cannot be told apart from the others or addressed in a PATCH /v1/telephony-lines/:number call.

See also