Remote PBX API

The PBX API provides a HTTP-based interface to the Axeos PBX. It allows e.g. monitoring PBX users and VoIP phones state, originating calls, and retrieving call statistics.
You can use the API to create  your own custom wall boards, smartphone apps, or to connect your own business software.

Starting from version 4.2.0 there is detailed API documentation (Swagger/Redoc) available through your PBX at https://[hostname]/apis/pbx/v1/docs and https://[hostname]/apis/pbx/v1/redoc.

Making API calls

API calls are made via HTTP (or HTTPS) requests to URIs under /apis/pbx/. For retrieving data ‘GET’ requests are used. The interface is available both through SSL (‘https:’) and via plain HTTP (‘http:’). Using HTTPS always is recommended. Insecure HTTP is disabled by default, if you wish to use it you can enable this manually via the PBX GUI: System / Options / API Key.

For example, to request a list of users on a ‘pbx.example.org’ PBX one makes a HTTP GET request to https://pbx.example.org/apis/pbx/users.

Authentication

Calls must be authenticated with either an API Key or, for limited functionality, with a PBX user name and its GUI password.

Your API Key can be set via the PBX GUI: System / Options / API Key.

There are two ways to provide the authentication credentials:

• Using the HTTP Basic authentication with the PBX username and password or apiKey as the username and the key for the password.
• Using GET request query parameter: in the query string use key with the value of the query string.
  E.g. https://pbx.example.org/apis/pbx/users?key=8d0a0704a96db1773fcb52db2f3e0979. This will work only for API Key and is generally not recommended.

Data format

The native format of data returned by these calls is JSON, but XML output is also available for most calls. There are two ways to request a specific data format:

• Using the HTTP ‘Accept’ request header field. Use ‘application/json’ to request JSON or ‘application/xml’ value for XML (deprecated).
• Using ‘.json’ or ‘.xml’ (deprecated) extension appended to the URI. Example: https://pbx.example.org/apis/pbx/users.json

JSON is returned by default and when unknown type is requested by the ‘Accept’ header field.

API Calls

System Information

/apis/pbx/system_information

New in PBX 4.1.10

• Request method: GET

Returns a single object with the following properties:

• uuid (string) – the PBX UUID
• version (string) – version of the PBX software
• language (string) – language, may be authenticated-user-specific
• time_zone (string) – configured time zone
• hostname (string) – fully qualified domain name of the PBX
• external_ipaddr (string) – preferred IP address to be used to contact the PBX (hostname should be used anyway)
• number (string) – best guess for the phone number this PBX or user can be contacted via. Initialized from caller-id settings. Not always a valid PSTN number, but in a typical setup it should be a proper ITU number.

Users

/apis/pbx/users – User list

• Request method: GET
  Parameters:
  • status (optional) – set to include user status (slower)
  • appid (optional) – include some extra application-specific user data

Returns the list of PBX users. Each entry has the following properties:

• uuid (string) – the user UUID – the unique immutable identifier of a user
• username (string) – the username
• full_name (string or null) – user’s full name
• phones (list of objects) – phones assigned to the user, for each:
  • type (string): “phone”, “hot-desk”, “number” or “trunk number”
  • phone (string): only when type==”phone” – UUID of the phone
  • number (string): only when type==”number” or type==”trunk number”
  • trunk (string): only when type==”trunk number” – UUID of the trunk
  • personal (bool): if it is a ‘personal’ phone (normally used only by one user)
• (OBSOLETE) primary_phone (string or null) – user’s primary SIP phone’s UUID

When status option is set in the query string, the following properties are also included:

• hot_desk (string or null) – the phone a hot-desk user is currently logged-in to
• call_forward (string or null) – Call Forward setting (the number where calls should be forwarded)
• cw (boolean) – current Call Waiting setting
• dnd (boolean) – current Do Not Disturb setting
• (OBSOLETE) phone (string or null) – the phone the user is currently available at (the one he is logged-in to, or the primary phone)

Please note, that request with status enabled may be slower and impose higher load on the PBX.

/apis/pbx/users/${uuid} – User status

• Request method:GET
• Parameters:
  • appid (optional) – include some extra application-specific user data

Returns information about a specific user including its current hot-desk status. The returned value contains the same properties as item on the user list requested with the status option set.

/apis/pbx/users/${uuid} – Set user settings

• Request method: POST
• Parameters: none

Request payload: object with the following properties (all are optional):

• call_forward (string or null) – new Call Forward setting value (the number where calls should be forwarded)
• cw (boolean) – new Call Waiting setting value
• dnd (boolean) – new Do Not Disturb setting value
• hot_desk (string or null) – the hot-desk phone to be assigned for a user

Changes current CW, DND and CF settings for a user, or binds user to a new hot-desk.

hot_desk can be set to null by a user, but setting this to a new phone is available only with apiKey authentication, as user cannot prove physical access to the device.

On success returns current user status (after the changes), like the GET request does.

Phones

/apis/pbx/phones – Phone list

• Request method: GET
• Parameters:
  • status – set to include user status (slower)

Returns the list of PBX phones. Each entry has the following properties:

• uuid (string) – the phone UUID – the unique immutable identifier of a phone
• name (string or null) – phone name (description)
• type (string) – phone type
• hot_desk (boolean) – whether hot-desk (mobile) users can log-in at this phone
• phone_username (string) – SIP username of the phone
• (OBSOLETE) mobile_logins_enabled (boolean) – same as ‘hot_desk’

When status option is set in the query string, the following properties are also included:

• status_code – device status code:
  • -2 – error reading status
  • -1 – not found
  • 0 – Idle
  • 1 — In Use
  • 2 — Busy
  • 4 — Unavailable
  • 8 – Ringing
  • 16 – On Hold
• status (string) – textual description of the device status
• hot_desk_user (string or null) – hot-desk user logged-in
• (OBSOLETE) mobile_user (string or null) – same as hot_desk_user

/apis/pbx/phones/${uuid} – Phone status

• Request method: GET
• Parameters: none

Returns information about a specific phone including its current status. The returned value contains the same properties as a user list item requested with status option enabled.

Voicemail

/apis/pbx/voicemail – Mailbox list

• Request method: GET
•  Parameters:
  • status – (optional) set to include mailbox status (slower)

Returns the list of voice mailboxes. When user authentication (and not apiKey) is used, only the user’s mailbox will be returned.

• uuid (string) – the mailbox UUID – the unique immutable identifier of a voice mailbox
• mailbox_number (string) – mailbox number (user visible identifier)

When status option is set in the query string, the following properties are also included:

• new_messages (integer) – number of new messages in the mailbox
• old_messages (integer) – number of old messages in the mailbox
• urgent_messages (integer) – number of urgent messages in the mailbox

Please note, that request with status enabled may be slower and impose higher load on the PBX.

/apis/pbx/voicemail/${uuid} – Voice mailbox status

• Request method: GET
• Parameters:
  • password – (optional) required to access mailbox other then the users own when not using apiKey

Returns status of a specific voice mailbox.

Returned properties:

• uuid (string) – the mailbox UUID – the unique immutable identifier of a voice mailbox
• mailbox_number (string) – mailbox number (user visible identifier)
• new_messages (integer) – number of new messages in the mailbox
• old_messages (integer) – number of old messages in the mailbox
• urgent_messages (integer) – number of urgent messages in the mailbox

Events

/apis/pbx/events – event polling

• Request method: GET
• Parameters:
  • last – sequence number of the last event already received
  • timeout – interval, in seconds, to wait for events
  • limit – maximum number of events to be sent

Allows to monitor user presence and phone statuses, by providing event polling interface. Allows multiple clients to read stream of PBX events via HTTP requests and provides basic error recovery facility. The API allows for continuous, real-time event reception via a regular HTTP connection. No websockets or specialized frameworks needed.

Returns: list of event objects. Each containing one event_type field, providing the type of the event, seq field, containing sequence number of the event, timestamp with ISO timestamp and several event-type-specific fields.

Usage

The client application should first ‘GET’ /apis/pbx/events without arguments. This will enable event gathering, if it has not yet been enabled, and wait for the first event(s) or return all recent events already in the buffer. If the application is not ready to read many events (like 1000, when the buffer is full), it should use the limit parameter in the query string.

After the first batch of events is received this way, the application should store the seq value of the last event received and use it for the last parameter in the next call, to receive the next batch.

Usually the next batch will start with event of seq = last + 1, but occasionally the sequence number won’t match. It may happen when:

• the PBX was restarted, events start from seq = 0
• buffer overflowed, but was not reset. Some events were dropped and the first received event has seq > last + 1
• buffer was reset – it overflowed and nobody was reading events. Many events were dropped. In such case event gathering was disabled to save PBX resources and the next batch will start from seq = 0

In all this cases application should continue with the new seq number received in the last event.

Empty result means a timeout occurred before any new events were recorded. The application should restart the request with the same last value.

In case of network error the request should also be restarted with the same last value.

To skip any past events, use the first request with limit=1, just to get the seq number for fetching upcoming events.

Phone and user status events

phone status update

Emitted when a device status is changed.

Event properties:

• phone_uuid – UUID of the phone
• status_code – status code
• status – status description

user logged in

Emitted when a hot-desk user logs-in at a phone.

Event properties:

• user_uuid – UUID of the user
• phone_uuid – UUID of the phone

user logged out

Emitted when a hot-desk user is logged-out from a phone.

Event properties:

• user_uuid – UUID of the user
• phone_uuid – UUID of the phone

user list changed

Emitted when the user list (as returned by /apis/pbx/users) has been changed.

phone list changed

Emitted when the phone list (as returned by /apis/pbx/phones) has been changed.

Call events

Call events are emitted for selected calls – this is configured through the ‘API events‘ dial plan action.

incoming call

Emitted when the ‘API events’ action rule is executed for a call. Provides basic information about the incoming call.

Event properties:

• event_tag – tag assigned by the ‘API events’ rule
• unique_id – call identifier
• account_code – accounting code assigned to the call
• called_did (optional) – the DID called
• called_extension (optional) – the extension called
• caller – caller data:
  • user_uuid (optional) – calling user UUID
  • phone_uuid (optional) – calling phone UUID
  • trunk_uuid (optional) – origin trunk UUID
  • number – current caller-id number
  • name – current caller-id name
  • normalized_number (optional) – normalized E.164 caller number
  • original_number (optional) – the original caller-id number

internal dial

Emitted when a local phone or phones are dialled for the call.

Event properties: the same as for incoming call, plus:

• targets – list of the dial targets, each one having:
• unique_id – identifier for the new call leg
• user_phone_type (when a user is called) – “phone“, “hot-desk“, “number” or “number on trunk” or “forward” when the call is being forwarded
• user_uuid (when a user is called) – called user UUID
• phone_uuid – called phone UUID (directly or as one of the phones for a user)
• trunk_uuid – called trunk for ‘number on trunk’ user device
• number – called number for ‘number’, ‘number on trunk’ user device or when the call is being forwarded

There might be multiple targets for a single user called.

call answered

Emitted when the call is answered on a local phone.

Event properties: the same as for incoming call, plus:

target – reached target, one of targets from the internal dial event.

call finished

Emitted when the call is hung up, or its monitoring has been finished for any other reason.

Event properties: the same as for incoming call, plus:

reason – one of:

• hangup – the call has been hung up
• expired – the call is very long or some events have been lost

blind transfer (New in PBX 4.1.9)

Emitted when the call is transferred blind.

Event properties: the same as for incoming call, plus:

• status – one of:
  • success – the transfer seems successful (doesn’t mean the call actually reached the target)
  • failure – the transfer failed (e.g. permission denied)
• transfer_extension – extension number used as transfer target
• transferer – details of the transferrer side of the transfer:
  • ‘unique_id‘ – unique id of one leg of the transferrer original connection (to match with other events)
  • ‘linked_id‘ – unique id of the other leg of this connection
  • ‘account_code‘ – account code of the transferrer
  • ‘number‘ – number of the transferrer
  • ‘name‘ – name of the transferrer (may be ‘< unknown >’)
• transferee – details of the transferee side of the transfer.
  • ‘unique_id‘ – unique id of one leg of the transferee connection (to match with other events)
    • ‘linked_id‘ – unique id of the other leg of this connection
  • ‘account_code‘ – account code of the transferee
  • ‘number‘ – number of the transferee
  • ‘name‘ – name of the transferee (may be ‘< unknown >’)

attended transfer (New in PBX 4.1.9)
Emitted when the call is transferred with the ‘attended transfer’ feature.

Event properties: the same as for incoming call (note: that might not be the call one is interested in. Check other unique_id values of transferer), plus:

• status – one of:
• success – the transfer seems successful (doesn’t mean the call actually reached the target)
• failure – the transfer failed (e.g. permission denied)
• transferer – details of the transferrer side of the transfer:
  • ‘unique_id_1’ – unique id of one leg of the transferrer connection #1 (to match with other events)
  • ‘unique_id_2’ – unique id of one leg of the transferrer connection #2 (to match with other events)
  • ‘linked_id_1’ – unique id of the other leg of the connection #1
  • ‘linked_id_2’ – unique id of the other leg of the connection #2
  • ‘account_code’ – account code of the transferrer
  • ‘number’ – number of the transferrer
  • ‘name’ – name of the transferrer (may be ‘< unknown >’)
• transferee – details of the transferee side of the transfer:
  • ‘unique_id’ – unique id of one leg of the transferee connection (to match with other events)
  • ‘linked_id’ – unique id of the other leg of this connection
  • ‘account_code’ – account code of the transferee
  • ‘number’ – number of the transferee
  • ‘name’ – name of the transferee (may be ‘< unknown >’)
• transfer_target – details of the transfer target side of the transfer:
  • ‘unique_id’ – unique id of one leg of the transfer target connection (to match with other events)
  • ‘linked_id’ – unique id of the other leg of this connection
  • ‘account_code’ – account code of the transfer target
  • ‘number’ – number of the transfer target
  • ‘name’ – name of the transfer target (may be ‘< unknown >’)

Other events

Originating calls

/apis/pbx/call – originate a call

• Request method: POST
• Parameters (in a JSON request body):
  • user_name or user_uuid (string) – selection of the calling user. Optional when authenticated as a user.
  • number (string) – number to dial – a local dial string (extension number or properly prefixed external number) or a ‘+’-prefixed E.164 number.
  • auto_answer (bool, optional) – should the caller phone auto-answer
  • phone_uuid (optional) – force to call *from* a specific phone. Phone must belong to the requesting user unless apiKey authentication is used.

On success returns ‘201 Created’ status code and a JSON object with the following properties:

• status – success for a successful call
• unique_id – an unique call identifier

The response includes a Location header providing URI for controlling the call.

When the caller device is not available (e.g. phone not registered) a ‘503 Service Not Available’ error response is generated.

Auto-answer option is available only, when a single specific phone is used, i.e. in one of the following situations:

• The user is logged-in on his hot-desk phone
• The user has only one, personal, phone
• The phone was specified using the phone_uuid option

When the connection to the caller cannot be established for a different reason (e.g. the device is busy) a ‘200 OK’ response is returned:

status – failure reason: ‘busy’, ‘no answer’ or ‘failed’.

/apis/pbx/call/ – call information

The request URI is the one returned in the Location header of the originate request or constructed from the unique_id returned in the originate request or in a call event.

• Request method: GET
• Parameters: none

When successful call information is returned, in the same format as used in call events.

404 response is returned when the call is not found. 403 response is returned when the caller has no privileges to control this call.

/apis/pbx/call/ – hangup a call

The request URI is the one returned in the Location header of the originate request or constructed from the unique_id returned in the originate request or in a call event.

• Request method: DELETE
• Parameters: none

When the action is performed ‘200’ response is returned with the following properties:

• status: success when hangup succeed
• message: verbose description of the result

404 response is returned when the call is not found. 403 response is returned when the caller has no privileges to control this call.

Switches

/apis/pbx/switches – User list

• Request method: GET
• Parameters:
  • status – set to include current status (slower)

Returns the list of PBX switches. Each entry has the following properties:

• uuid (string) – the switch UUID – the unique immutable identifier of a switch
• name (string) – the switch name
• default (bool) – default value

When status option is set in the query string, the following property is also included:

value (string or null) – current value of the switch

Please note, that request with status enabled may be slower and impose higher load on the PBX.

/apis/pbx/switches/${uuid} – Get switch status

• Request method: GET
• Parameters: none

Returns information about a specific switch including its current status. The returned value contains the same properties as item on the switch list requested with the status option set.

/apis/pbx/switches/${uuid} – Set switch status

• Request method: POST
• Parameters:
  • value – new value to set

Changes current value of a PBX switch.

ACD Statistics

/apis/pbx/acd/stats – Statistics for all queues

• Request method: GET, POST
• Parameters:
  • agents – when set, then per-agent details are included
  • calls – when set, then per-call details are included
  • relative – when set, then some values will be returned relative to the last reset
  • reset (POST only) – statistics reset request (implies relative)

Returns the list of known ACD queues. Each entry has the following properties:

• calls_waiting (integer) – number of calls currently waiting in the queue
• longest_hold_time (integer) – time in seconds, the oldest call in the queue is already on hold
• hold_time (integer) – average time in seconds calls are on hold in the queue
• talk_time (integer) – average ‘talk time’ for the queue
• answered (integer) – number of answered calls. Counted since the last reset when in relative mode.
• aborted (integer) – number of calls hung up before they were answered by an agent. Counted since the last reset when in relative mode.
• service_level (float) and service_level_interval – service level (% of calls answered within X seconds)
• all_agents (integer) – number of agents assigned to the queue
• logged_in_agents (integer) – number of agents logged in
• free_agents (integer) – number of agents assigned to the queue and not busy at the moment
• available_agents (integer) – similar to free_agents but may include some agents whose state is not known
• agents – optional list of agent details
• calls – optional list of call details
• relative (boolean) – when relative statistics were requested, True if returned values are not absolute (after at least one reset)
• last_reset (string) – ISO 8601 timestamp of the last statistics reset
• calls_taken (integer) – sum of all calls taken by the all agents in the queue, may include calls via other queues (new in 4.1.6)

Properties of the objects in the optional agents list:

• calls_taken (integer) – number of calls taken by the agent. Counted since the last reset when in relative mode.
• last_call (string) – ISO 8601 timestamp of the last call taken. Can be reset for relative mode.
• name (string) – name of the agent (currently the PBX user name)
• paused (boolean) – whether the agent is currently paused or not
• penalty (integer) – agent’s ‘penalty’ value
• status (string) – agent’s device status
• status_code (integer) – numeric value for the agent’s device status
• user_uuid (string) – agent PBX user UUID

Properties of the objects in the optional calls list:

• callerid_name (string) – caller-id name of the caller
• callerid_num (string) – caller-id number of the caller
• position (integer) – position in the queue
• wait (integer) – time in seconds the call is waiting in the queue (AXPBX-294)

/apis/pbx/acd/${uuid}/stats – Statistics for a specific queue

Same as above, but returns data for the selected queue only.