Extensions and devices
Routes: /extensions and /devices (see /api/docs for the full reference).
Extensions
The Extensions page.
An extension is a dialable number inside a company.
| Field | Meaning |
|---|---|
number | 1 to 16 digits, unique per company. |
kind | What the number reaches: user, queue, ivr, ringgroup, conference, park, paging or fax. Default user. |
user_id | The owner, only for kind = user. A user has at most one extension. |
display_name | Shown on phones and in the directory. For an owned extension it defaults to the user's name. |
enabled | Disabled extensions are not routable. |
target_flow_id | Only for kind = ivr: the IVR menu or call flow an internal call to the number runs (see IVR menus). null means none. |
Permissions: extensions:read and extensions:write, both department-scoped.
An extension belongs to the department of its owner. An extension without an owner (a queue, IVR, ring group or reserved number) is company-wide, so it needs the company-wide permission. To detach an owner, PATCH with remove_owner: true. Deleting an extension also removes its devices.
Giving an extension to, or taking one from, an account that holds a system role is refused for company principals (MPBX-ACCOUNT-SYSTEM).
Devices
The Devices page. SIP user names are blurred; SIP passwords are never shown.
A device is one SIP identity (a desk phone, softphone or app) of an extension.
| Field | Meaning |
|---|---|
extension_id | The extension it belongs to. |
name | A label for the device. |
sip_username | Generated by the server. |
transport_policy | Which SIP transports the device may use. |
mac, model, provisioning_template | Optional hardware details. An empty string on PATCH clears them. |
has_credentials | Whether the device has SIP credentials. The credentials themselves are never shown by the device routes. |
revoked_at | Set when the device was revoked. |
Permissions: devices:read and devices:write, department-scoped through the extension's owner.
POST /devices/{id}/revoke removes the device's credentials and stops it from registering. Creating and rotating the credentials is a separate per-device flow that is not part of these routes.
Live registrations are published as device events on the events WebSocket to holders of devices:read.
Automatic phone provisioning
Desk phones (Yealink, Fanvil, Snom, Grandstream) are configured automatically from their MAC address. See Desk phone provisioning. To connect an app or a browser, see Add users, extensions and phones.