Devices in the API | VirtualPBX

Devices are the endpoints assigned to an account, and the Devices API lists them, reads one device, and updates device fields. A phone, an application, or another endpoint on the account is a device in this API. Use the list request to see what is provisioned, then the single-device request when a change should touch only one endpoint. The schema on this page names the fields those requests accept.

About Devices

Devices are the endpoints assigned to an account that serve that account’s needs.

Devices like fax machines, SIP phones, softphone clients, and cell phones (via call forwarding), among others, can be represented by devices.

Schema Reference

Schema

List Devices

List all devices on the account.

API

Method: GET

https://public-api.virtualpbx.com:8443/v2/accounts/{{account_id}}/devices

CURL Example

curl --location -g --request GET 'https://public-api.virtualpbx.com:8443/v2/accounts/{ACCOUNT_ID}/devices' \
--header 'X-Auth-Token: {AUTH_TOKEN}' \
--header 'Content-Type: application/json'

Get Device

Returns a device configuration.

API

Method: GET

https://public-api.virtualpbx.com:8443/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "call_restriction": {},
        "caller_id": {},
        "contact_list": {},
        "dial_plan": {},
        "enabled": true,
        "exclude_from_queues": false,
        "id": "{DEVICE_ID}",
        "media": {
            "audio": {
                "codecs": [
                    "PCMU"
                ]
            },
            "encryption": {
                "enforce_security": false,
                "methods": []
            },
            "video": {
                "codecs": []
            }
        },
        "music_on_hold": {},
        "mwi_unsolicitated_updates": true,
        "name": "New Device",
        "register_overwrite_notify": false,
        "ringtones": {},
        "sip": {
            "invite_format": "username",
            "method": "password",
            "registration_expiration": 300
        },
        "suppress_unregister_notifications": false
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

CURL Example

curl --location -g --request GET 'https://public-api.virtualpbx.com:8443/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}' \
--header 'X-Auth-Token: {AUTH_TOKEN}' \
--header 'Content-Type: application/json'

Update Device

Changes a device configuration. Including “sync”: true in the “data” will attempt to reboot the phone.

API

Method: POST

https://public-api.virtualpbx.com:8443/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}

CURL Example

curl --location -g --request POST 'https://public-api.virtualpbx.com:8443/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}' \
--header 'X-Auth-Token: {AUTH_TOKEN}' \
--header 'Content-Type: application/json'

List Registrations

This will fetch the current registrations of any devices. If no devices are registered, an empty list will be returned.

API

Method: DELETE

https://public-api.virtualpbx.com:8443/v2/accounts/{ACCOUNT_ID}/devices/status

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "device_id": "{DEVICE_ID}",
            "registered": true
        }
    ],
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Reboot Device

Some devices support receiving SIP NOTIFY packets with event = check-sync. This is typically used to reboot the phone if the configuration has changed. VirtualPBX will generate the NOTIFY packet if the device is registered.

API

Method: POST

https://public-api.virtualpbx.com:8443/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/sync

CURL Example

curl --location -g --request POST 'https://public-api.virtualpbx.com:8443/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/sync' \
--header 'X-Auth-Token: {AUTH_TOKEN}' \
--header 'Content-Type: application/json'