--- notionId: "0ab5f3570ad84bb6a7b3ccb1a8292999" product: "developer" cluster: "apis" intent: "developer.api-devices" docSlug: "api-devices" task: "Devices in the API" title: "Devices in the API | VirtualPBX" meta_description: "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" answer: "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." audience: "user" updated: "2022-12-06" legacy: ["devices"] headings: [{"depth":2,"text":"About Devices","id":"about-devices"},{"depth":3,"text":"Schema Reference","id":"schema-reference"},{"depth":3,"text":"List Devices","id":"list-devices"},{"depth":3,"text":"API","id":"api"},{"depth":3,"text":"CURL Example","id":"curl-example"},{"depth":3,"text":"Get Device","id":"get-device"},{"depth":3,"text":"API","id":"api-1"},{"depth":3,"text":"Response","id":"response"},{"depth":3,"text":"CURL Example","id":"curl-example-1"},{"depth":3,"text":"Update Device","id":"update-device"},{"depth":3,"text":"API","id":"api-2"},{"depth":3,"text":"CURL Example","id":"curl-example-2"},{"depth":3,"text":"List Registrations","id":"list-registrations"},{"depth":3,"text":"API","id":"api-3"},{"depth":3,"text":"Response","id":"response-1"},{"depth":3,"text":"Reboot Device","id":"reboot-device"},{"depth":3,"text":"API","id":"api-4"},{"depth":3,"text":"CURL Example","id":"curl-example-3"}] lint: [] --- ## 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'