Create connection

POST /v1/voximplant-sip

Creates a SIP connection to an office or cloud PBX. The Bitrix24 account receives and makes calls through this connection. The body is a flat JSON object.

Request fields (body)

Field	Type	Required	Description
`server`	string	yes	SIP server address
`login`	string	yes	Login on the SIP server
`password`	string	no	Connection password. Not returned in responses — the `hasPassword` flag is returned instead
`type`	string	no	PBX type: `office` — office PBX, `cloud` — cloud PBX. Defaults to `cloud`. The type cannot be changed after creation
`title`	string	no	Connection name

All values are strings. The body accepts no other fields.

Examples

curl — personal key

Terminal

curl -X POST "https://vibecode.bitrix24.com/v1/voximplant-sip" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "office",
    "title": "Office PBX",
    "server": "sip.example.com",
    "login": "office-line",
    "password": "EXAMPLE_SIP_PASSWORD"
  }'

curl — OAuth application

Terminal

curl -X POST "https://vibecode.bitrix24.com/v1/voximplant-sip" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "office",
    "title": "Office PBX",
    "server": "sip.example.com",
    "login": "office-line",
    "password": "EXAMPLE_SIP_PASSWORD"
  }'

JavaScript — personal key

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/voximplant-sip', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'office',
    title: 'Office PBX',
    server: 'sip.example.com',
    login: 'office-line',
    password: 'EXAMPLE_SIP_PASSWORD',
  }),
})

const { success, data } = await res.json()
if (success) {
  console.log('Created connection', data.configId, 'incoming server:', data.incomingServer)
}

JavaScript — OAuth application

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/voximplant-sip', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'office',
    title: 'Office PBX',
    server: 'sip.example.com',
    login: 'office-line',
    password: 'EXAMPLE_SIP_PASSWORD',
  }),
})

const { success, data } = await res.json()
if (success) {
  console.log('Created connection', data.configId, 'incoming server:', data.incomingServer)
}

Response fields

A successful request returns status 201. Passwords are not included in the response — the hasPassword and hasIncomingPassword flags are returned instead.

Field	Type	Description
`success`	boolean	`true` on success
`data.id`	string	ID of the created connection, same as `configId`
`data.configId`	string	Connection ID — used to get, update, and delete the connection
`data.type`	string	PBX type: `office` — office PBX, `cloud` — cloud PBX
`data.title`	string	Connection name
`data.server`	string	SIP server address
`data.login`	string	Login on the SIP server
`data.hasPassword`	boolean	Whether the connection password is set
`data.authUser`	string \| null	User name for authentication on the SIP server. `null` if not set
`data.outboundProxy`	string \| null	Proxy server address for outgoing calls. `null` if not set
`data.detectLineNumber`	string	Whether to detect the line number from the SIP headers of an incoming call: `N` — do not detect
`data.lineDetectHeaderOrder`	string	SIP headers used to detect the line number, in the order they are checked, for example `diversion;to`
`data.registrationStatusCode`	string \| null	Result code of registration on the SIP server. `null` right after creation
`data.registrationErrorMessage`	string \| null	Registration error text. `null` if there is no error
`data.regId`	number	Cloud PBX only: registration ID on the SIP server. A number in the create response, a string in the list and get responses
`data.incomingServer`	string	Office PBX only: server address for incoming calls, issued by Bitrix24
`data.incomingLogin`	string	Office PBX only: login for incoming calls, issued by Bitrix24
`data.hasIncomingPassword`	boolean	Office PBX only: whether the password for incoming calls is set

Response example

JSON

{
  "success": true,
  "data": {
    "id": "17",
    "type": "office",
    "configId": "17",
    "server": "sip.example.com",
    "login": "office-line",
    "hasPassword": true,
    "incomingServer": "ip.b24-1234-1234567890.bitrixphone.com",
    "incomingLogin": "sip17",
    "hasIncomingPassword": true,
    "authUser": null,
    "outboundProxy": null,
    "detectLineNumber": "N",
    "lineDetectHeaderOrder": "diversion;to",
    "registrationStatusCode": null,
    "registrationErrorMessage": null,
    "title": "Office PBX"
  }
}

Error response example

400 — server or login is missing: