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
number string yes Unique line identifier in the Bitrix24 account
name string no Display name of the line
crmAutoCreate boolean no Auto-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
success boolean Always true on success
data.id string The 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
400 READONLY_FIELD The body carries a read-only field — serverName
422 BITRIX_ERROR Bitrix24 returned an error — text in error.message. Causes: number not provided, duplicate identifier
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
502 BITRIX_UNAVAILABLE Bitrix24 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