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

Add a line

POST /v1/telephony-lines

Registers a new external application line in the Bitrix24 account. After creation the line is available in GET /v1/telephony-lines and can be used as fromLine in outbound calls. Fields are passed flat at the JSON root — without a fields wrapper.

Request fields (body)

Field Type Required Description
Fieldnumber Typestring Requiredyes DescriptionUnique line identifier in the Bitrix24 account
Fieldname Typestring Requiredno DescriptionDisplay name of the line
FieldcrmAutoCreate Typeboolean Requiredno DescriptionAuto-create a CRM entity on an outbound call through the line: true — create, false — do not. Defaults to true

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/telephony-lines" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "sip-line-1",
    "name": "Main line",
    "crmAutoCreate": false
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/telephony-lines" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "sip-line-1",
    "name": "Main line",
    "crmAutoCreate": false
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/telephony-lines', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    number: 'sip-line-1',
    name: 'Main line',
    crmAutoCreate: false,
  }),
})

const { success, data } = await res.json()
console.log('Line identifier:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/telephony-lines', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    number: 'sip-line-1',
    name: 'Main line',
    crmAutoCreate: false,
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typestring DescriptionThe submitted number — the addressable line identifier for subsequent operations

Response example

JSON 
{
  "success": true,
  "data": {
    "id": "sip-line-1"
  }
}

Error response example

422 — the number field was not provided:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "NUMBER should not be empty"
  }
}

Errors

HTTP Code Description
HTTP400 CodeREADONLY_FIELD DescriptionThe body carries a read-only field — serverName
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error — text in error.message. Causes: number not provided, duplicate identifier
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
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable

Full list of common API errors — Errors.

Known specifics

serverName is read-only, and a write is rejected. Bitrix24 neither stores nor returns the field, so the write is rejected before Bitrix24 is called: both create and update respond 400 READONLY_FIELD. Previously create answered 201 while the value was silently lost. The field itself stays visible in GET /v1/telephony-lines/fields marked read-only, so its meaning is still discoverable.

The crmAutoCreate field is a camelCase boolean. Pass true/false; if omitted, the line is created with the default value true. Previously only the UPPER_SNAKE name CRM_AUTO_CREATE was accepted as a "Y"/"N" string and crmAutoCreate was silently dropped — since 07.2026 the canonical form is a camelCase boolean (the raw UPPER variant is still accepted on write for compatibility).

data.id matches the submitted number. Use this value in the PATCH /v1/telephony-lines/:number and DELETE /v1/telephony-lines/:number URLs. Values with +, spaces, or / are allowed — when substituted into the URL they must be encoded: +12025550123 → %2B12025550123.

See also