# SIP connections

Manage SIP connections of office and cloud PBXs through which the Bitrix24 account receives and places calls.

**Scope:** `telephony` | **Base URL:** `https://vibecode.bitrix24.com/v1` | **Authorization:** `X-Api-Key`

## What to know before you start

1. **Two PBX types.** `cloud` is a cloud PBX, `office` is an office PBX. The type is set on creation, defaults to `cloud`, and cannot be changed afterwards. For an office PBX, Bitrix24 issues an address and a login for incoming calls on creation — the `incomingServer` and `incomingLogin` fields.
2. **Passwords are write-only.** `password` is passed on create and update but never comes back in a response: responses carry the `hasPassword` and `hasIncomingPassword` flags instead of passwords. The list cannot be filtered or sorted by these flags.
3. **Five fields can be set through the API:** `type`, `title`, `server`, `login`, `password`. All other connection fields are read-only, and an extra field in the request body returns `400 READONLY_FIELD`.
4. **Only your own application's connections are visible.** The methods in this section work with connections created by the same Bitrix24 application as the key: an application key works with its own application's connections; a personal key works with connections created through the Bitrix24 account's webhooks. Another application's connection does not appear in the list, and the methods return `404 ENTITY_NOT_FOUND` for its `configId`.
5. **The type of `configId` depends on the method.** List, get, create and update responses return it as a string; the delete response returns it as a number. In the path the ID is passed as a number: `/v1/voximplant-sip/17`.

## Quick start

List the SIP connections available to the key:

```bash
curl "https://vibecode.bitrix24.com/v1/voximplant-sip" \
  -H "X-Api-Key: YOUR_API_KEY"
```

The response contains an array of connections in `data` and their count in `meta.total`. Connection fields are described on the [List connections](/docs/voximplant-sip/list) page.

## Full example

An office PBX connection from creation to deletion: create it, read it, change the login and password, delete it. Run the script in Node.js 18+ from a file with the `.mjs` extension.

```javascript
const BASE = 'https://vibecode.bitrix24.com/v1/voximplant-sip'
const API_KEY = 'YOUR_API_KEY'

async function call(method, path, body) {
  const headers = { 'X-Api-Key': API_KEY }
  if (body) headers['Content-Type'] = 'application/json'
  const res = await fetch(BASE + path, { method, headers, body: body && JSON.stringify(body) })
  const json = await res.json()
  if (!json.success) throw new Error(`${json.error.code}: ${json.error.message}`)
  return json.data
}

// 1. Create an office PBX connection
const created = await call('POST', '', {
  type: 'office',
  title: 'Office PBX',
  server: 'sip.example.com',
  login: 'office-line',
  password: 'EXAMPLE_SIP_PASSWORD',
})
console.log('Created:', created.configId, 'incoming server:', created.incomingServer)

// 2. Read the connection
const sip = await call('GET', `/${created.configId}`)
console.log('Type:', sip.type, 'password set:', sip.hasPassword)

// 3. Change the login and password
const updated = await call('PATCH', `/${created.configId}`, {
  login: 'office-line-2',
  password: 'EXAMPLE_NEW_SIP_PASSWORD',
})
console.log('New login:', updated.login)

// 4. Delete the connection
const removed = await call('DELETE', `/${created.configId}`)
console.log('Deleted:', removed.deleted)
```

## Endpoint reference

| Method | Path | Bitrix24 method | Description |
|-------|------|---------------|----------|
| GET | [`/v1/voximplant-sip`](/docs/voximplant-sip/list) | voximplant.sip.get | List connections with filtering, sorting and pagination |
| GET | [`/v1/voximplant-sip/:configId`](/docs/voximplant-sip/get) | voximplant.sip.get | A single connection by ID |
| POST | [`/v1/voximplant-sip`](/docs/voximplant-sip/create) | voximplant.sip.add | Create a connection |
| PATCH | [`/v1/voximplant-sip/:configId`](/docs/voximplant-sip/update) | voximplant.sip.update | Change the title, server, login or password |
| DELETE | [`/v1/voximplant-sip/:configId`](/docs/voximplant-sip/delete) | voximplant.sip.delete | Delete a connection |

## Error codes

### SIP connection errors

| HTTP | Code | When |
|------|-----|-------|
| 400 | `INVALID_PARAMS` | Invalid list parameters `filter`, `sort`, `order`, `start`; `configId` is not a positive integer; the body is not a JSON object; `type` is neither `office` nor `cloud`; a field value is not a string; an update contains no field other than `type` |
| 400 | `MISSING_REQUIRED_FIELDS` | `server` or `login` is missing on create |
| 400 | `READONLY_FIELD` | The body contains a field other than `type`, `title`, `server`, `login`, `password`; or on update `type` differs from the current one |
| 404 | `ENTITY_NOT_FOUND` | No connection with this `configId` among the connections available to the key |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request or did not confirm the update or deletion; the reason is in `error.message` |

### System errors

| HTTP | Code | When |
|------|-----|-------|
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `INVALID_API_KEY` | The platform does not recognize the key string: a typo, a truncated value, or a deleted key |
| 401 | `TOKEN_MISSING` | The key has no access to the portal: a personal key has no portal webhook, or an application key was sent without a session token in `Authorization: Bearer` |
| 403 | `SCOPE_DENIED` | The key lacks the `telephony` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | A read-only key attempts to create, update or delete a connection |
| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access — [causes explained](/docs/errors/auth#bitrix_access_denied-403) |
| 429 | `RATE_LIMITED` | Request rate exceeded |
| 429 | `QUEUE_OVERFLOW` | The account request queue is full, so the request is rejected without waiting. The `Retry-After` header suggests the delay |
| 429 | `QUEUE_TIMEOUT` | The request did not get through the account queue in time and was not sent to Bitrix24. The `Retry-After` header suggests the delay |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable |
| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time |

Full list of common API errors — [Errors](/docs/errors).

## See also

- [Default outgoing line](/docs/voximplant-lines/default)
- [Employee telephony settings](/docs/telephony-users)
- [Calls](/docs/calls)
- [Telephony](/docs/telephony)