Devices API

Devices on your VoIP account refer to hardware such as fax machines, SIP phones, soft phone clients, cell phones (through call forwarding), and so on. Use the Devices API to send and receive requests related to managing your devices.

API calls

Click on each call to view the endpoint, method, and request example.

Parameters

The table shows the possible parameters available for devices requests.

Key Description Type Options/Min/Max/Default
name Required. A friendly name for the device. string (1..128)
call_forward The call forwarding parameters for the device. object
call_forward.direct_calls_only Determines if the calls that are not directly sent to the device should be forwarded. boolean The default is false.
call_forward.enabled Determines if the call forwarding should be used. boolean The default is false.
call_forward.failover Enable the call-forwarding parameters if the device is offline. boolean The default is false.
call_forward.ignore_early_media The option to determine if early media from the call forwarded number should ignored. boolean The default is true .
call_forward.keep_caller_id Determines if the caller ID is kept when the call is forwarded. If false, then the device caller ID is used. boolean The default is true .
call_forward.number The number that calls should be forwarded to. string (0..15)
call_forward.require_keypress Determines if the callee is prompted to press 1 to accept the call. boolean The default is true .
call_forward.substitute Determines if the call forwarding replaces the device. boolean The default is true .
call_restriction Device level call restrictions for each available number classification object
call_waiting See Call waiting parameters.
caller_id See Caller ID parameters. object
contact_list Contact list parameters. See Contacts. object
contact_list.exclude If set to true, then the device is excluded from the contact list boolean
device_type An arbitrary device type used by the UI and billing system string
dial_plan A list of rules used to modify dialed numbers. object
do_not_disturb.enabled Indicates if the "do-not-disturb" feature is enabled for this device. boolean
enabled Determines if the device is currently enabled. boolean The default is true.
exclude_from_queues If set to true, this parameter means that the system should not ring this device when calling an agent in the queue. boolean The default is false.
language The language for the device. string
media The device media parameters. object
media.audio The audio media parameters. object
media.audio.codecs A list of audio codecs the device supports . array (OPUS, CELT@32000h, G7221@32000h, G7221@16000h, G722, speex@32000h, speex@16000h, PCMU, PCMA, G729, GSM, CELT@48000h, CELT@64000h, G722_16, G722_32, CELT_48, CELT_64, Speex, speex). The default is PCMU.
media.audio.codecs.[] Specific audio codecs. string
media.bypass_media The default bypass media mode. boolean true, false, auto
media.encryption Encryption parameters. object
media.encryption.enforce_security Indicates if encryption is enabled. boolean The default is false.
media.encryption.methods Supported encryption types array (string)zrtp, srtp)
media.encryption.methods.[] Specific encryption types. string
media.fax_option Indicates if T.38 is supported. boolean
media.ignore_early_media Indicates if early media from the device should always be ignored. boolean
media.progress_timeout The progress timeout to apply to the device (seconds). integer
media.video The video media parameters. object
media.video.codecs A list of video codecs the device supports. array (string)(VP8, H264, H263, H261)
media.video.codecs.[] Specific codecs. string
metaflows The device metaflow parameters #/definitions/metaflows
music_on_hold The music on hold parameters that should be used if not a property of the device owner. object
music_on_hold.media_id The ID of a media object that should be used as the music on hold. string (0..128)
mwi_unsolicitated_updates When this parameter is set to true, it enables unsolicitated message-waiting indicator (MWI) notifications. boolean The default is true.
outbound_flags List of flags (features) this device requires when making outbound calls array (string)
owner_id The ID of the user object that 'owns' the device. string (32)
presence_id Static presence ID (used instead of SIP username). string
provision Provision data. object
provision.feature_keys Feature keys. object
provision.feature_keys./^[0-9]+$/ Specific feature keys. object null
register_overwrite_notify When this parameter is set to true, it enables overwrite notifications. boolean The default is false.
ringtones Ringtone parameters. object
ringtones.external The alert info SIP header that is added when the call is from external sources. string (0..256)
ringtones.internal The alert info SIP header that is added when the call is from internal sources. string (0..256)
sip SIP parameters. object
sip.custom_sip_headers A property list of SIP headers beginning with the prefix X-. object
sip.expire_seconds The time, in seconds, sent to the provisioner for the registration period that the device should be configured with. integer The default is 300.
sip.ignore_completed_elsewhere When this parameter is set to false, the phone should not consider ring group calls that were answered elsewhere as missed calls. boolean
sip.invite_format The SIP request URI invite format. string username, npan, 1npan, e164, route. The default is username .
sip.ip The IP address for this device. string
sip.method The method of authentication. string password or ip. The default is password.
sip.number The number used if the invite format is 1npan, npan, or e164 . If the invite format is not set, then the dialed number is used. string
sip.password SIP authentication password. string (5..32)
sip.realm The realm this device should use, overriding the account realm. (This parameter is not often used.) string
sip.route The SIP URL used if the invite format is route . string
sip.static_route Sends all inbound calls to this string (instead of dialed number or username). string
sip.username The SIP authentication username. string (2..32)
suppress_unregister_notifications If set to true this parameter disables notifications about deregistration. boolean The default is false.
timezone The timezone the device is set up with. string

Call waiting attributes - parameters for server-side call waiting

Key Description Type Options/Min/Max/Default
enabled Determines if server side call waiting is enabled or disabled. boolean The default is false.

Caller ID attributes - parameters for caller ID settings based on the type of call.

Key Description Type Options/Min/Max/Default
emergency The caller ID used when a resource is flagged as 'emergency'. object
emergency.name The caller ID name for the object type when a resource is flagged as 'emergency'. string (0..35)
emergency.number The caller ID number for the object type when a resource is flagged as 'emergency'. string (0..35)
external The default caller ID used when dialing external numbers. object
external.name The caller ID name for the object type when dialing external numbers. string (0..35)
external.number The caller ID number for the object type when dialing external numbers. string (0..35)
internal The default caller ID used when dialing internal extensions. object
internal.name The caller ID name for the object type when dialing internal extensions. false
internal.number The caller ID number for the object type when dialing internal extensions. string (0..35)

Dialplan attributes - permits local dialing by converting the dialed number to a routable form.

Key Description Type Options/Min/Max/Default
system List of system dial plans. array(object) The default is false.

Metaflow attributes - a metaflow node defines a module to execute, data to provide to that module, and one or more children to branch to.

Key Description Type Options/Min/Max/Default
module Required. The name of the metaflow module to execute at this node. string (1..64)
children 8 Children metaflows. object
children./.+/ Specific children. string
data The data/arguments of the metaflow module. object

Metaflows attributes - metaflows are actions applied to a call outside of the normal callflow, initiated by the caller(s).

Key Description Type Options/Min/Max/Default
binding_digit What DTMF will trigger the collection and analysis of the subsequent DTMF sequence string 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, *, #
digit_timeout Indicates how many milliseconds the system should wait between DTMF presses before processing the collected sequence. integer
listen_on Specifies which leg of the call to listen to for DTMF string both, self, peer
numbers A list of static numbers with their flows. object
numbers./^[0-9]+$/ Specific numbers. false
patterns A list of patterns with their flows object
patterns./.+/ Specific patterns. string

Get summary of devices

Returns a list of all devices in the account.

Method and endpoint

GET /v2/accounts/{ACCOUNT_ID}/devices

Request

curl -v -X GET \
    -X "X-Auth-Token: {AUTH_TOKEN} \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/devices

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "device_type": "sip_device",
            "enabled": false,
            "id": "{DEVICE_ID}",
            "mac_address": "00:04:f2:ab:7e:fd",
            "name": "MyPolycom"
        }
    ],
    "page_size": 1,
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Create a device

Creates a device. See Attributes for parameters that you can include in the data portion.

Method and endpoint

PUT /v2/accounts/{ACCOUNT_ID}/devices

Request

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN} \
    -H "Content-Type: application/json" \
    -d '{"data":{"name":"New Device"}}' \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/devices

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"
}

Remove a device

Removes a device from the account.

Method and endpoint

  DELETE /v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}

Request

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    https://apps.hostedpbx.ie: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"
}

Get a device

Returns details of a specific device.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    https://apps.hostedpbx.ie: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"
}

Change a device

Updates the device data.

NOTE: Including "sync":true in the "data" triggers an attempt to reboot the phone.

Method and endpoint

POST /v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}

Request

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{"data":{
        "name": "new device",
        "call_restriction": {},
        "caller_id": {},
        "contact_list": {},
        "dial_plan": {},
        "enabled": true,
        "exclude_from_queues": false,
        "media": {
            "audio": {"codecs": ["PCMU"]},
            "encryption": {"enforce_security": false, "methods": []},
            "video": {"codecs": []}
        },
        "music_on_hold": {},
        "mwi_unsolicitated_updates": true,
        "register_overwrite_notify": false,
        "ringtones": {},
        "sip": {
            "invite_format": "username",
            "method": "password",
            "registration_expiration": 300
        },
        "suppress_unregister_notifications": false,
        "id": "4f3330e78e664bb57f8fb23fbaac2429"
        }}' \
    https://apps.hostedpbx.ie: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"
}

Patch a device

Updates a device using a partial update patch request.

Method and endpoint

PATCH /v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}

Request

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data":{"presence_id":"dis_my_device"}}' \
    https://apps.hostedpbx.ie: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",
        "presence_id":"dis_my_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"
}

Get registration status of all devices

Gets the current registrations of any devices. If no devices are registered, an empty list is returned.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/devices/status

Request

    curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    https://apps.hostedpbx.ie: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 a device

Reboots a device or phone after the configuration has changed.

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

Method and endpoint

POST /v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/sync

Request

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/sync

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": "sync request sent",
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Execute a quick call

Enables you to ring the device. After it is answered, you connect to {PHONE_NUMBER}.

NOTE: In this scenario, the device is considered the callee while the {PHONE_NUMBER} side is considered the caller (helpful to know when debugging a call.

Parameters

The table shows the possible parameters included in the call request.

Key Description Type Options/Min/Max/Default
auto_answer If this parameter is supported and set to true, it tells the SIP phone to auto-answer the call. boolean
cid-name The caller ID name. string The default is Device QuickCall.
cid-number The caller ID number. string The default is {PHONE_NUMBER}).
ignore-early-media Indicates whether to ignore early media. boolean
media Indicates whether to go peer-to-peer (bypass with the RTP). string bypass, process
number_filter If set to true, this parameter removes non-alphanumeric characters. If it is a regex, use the first capture group as the "number" to dial. boolean, regex
timeout Specifies how many seconds the device should ring for before timing out. integer (3..)

Method and endpoint

GET /v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/quickcall/{PHONE_NUMBER}

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/quickcall/{PHONE_NUMBER}

Response

{
  "auth_token": "{AUTH_TOKEN}",
  "data": {
    "export_custom_channel_vars": [
      "Account-ID",
      "Retain-CID",
      "Authorizing-ID",
      "Authorizing-Type"
    ],
    "custom_channel_vars": {
      "authorizing_id": "{DEVICE_ID}",
      "authorizing_type": "device",
      "inherit_codec": "false",
      "retain_cid": "true",
      "account_id": "{ACCOUNT_ID}"
    },
    "continue_on_fail": false,
    "dial_endpoint_method": "simultaneous",
    "outbound_callee_id_number": "{DEVICE_CALLER_ID_NUMBER}",
    "outbound_callee_id_name": "{DEVICE_CALLER_ID_NAME}",
    "outbound_caller_id_number": "{E164_NUMBER}",
    "outbound_caller_id_name": "Device QuickCall",
    "media": "process",
    "ignore_early_media": true,
    "timeout": 30,
    "endpoints": [
      {
        "outbound_call_id": "{CALL_ID}-quickcall",
        "custom_channel_vars": {
          "auto_answer": true,
          "authorizing_id": "{DEVICE_ID}",
          "owner_id": "{USER_ID}",
          "account_id": "{ACCOUNT_ID}",
          "media_encryption_enforce_security": false,
          "sip_invite_domain": "{ACCOUNT_REALM}"
        },
        "custom_sip_headers": {
          "x_hostedpbx_aor": "sip:{DEVICE_SIP_USER}@{ACCOUNT_REALM}"
        },
        "presence_id": "{PRESENCE_ID}",
        "codecs": [
          "PCMU",
          "PCMA"
        ],
        "endpoint_id": "{DEVICE_ID}",
        "to_did": "{E164_NUMBER}",
        "to_realm": "{ACCOUNT_REALM}",
        "to_username": "{DEVICE_SIP_USER}",
        "to_user": "{DEVICE_SIP_USER}",
        "invite_format": "username"
      }
    ],
    "application_data": {
      "route": "{PHONE_NUMBER}"
    },
    "application_name": "transfer"
  },
  "status": "success",
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}"
}

Adding ringtones

To setup internal and external ringtones, add the following:

{
    "name": "Device with custom ringtones",
    "ringtones": {
        "internal": "alert info SIP header",
        "external": "alert info SIP header"
    }
}

See the following example for Polycom.

Get user devices

Returns a list of devices that belong to a user, or devices that a user has hot-desked into.

NOTE: The first device, {DEVICE_ID_1} is owned by {USER_ID} but the second device, {DEVICE_ID_2}, is owned by {OWNER_ID} and is currently hotdesked to {USER_ID}. See the "hotdesked":true attribute).

Method and endpoint

GET /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/devices

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/devices

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "device_type": "sip_device",
            "enabled": true,
            "hotdesked": false,
            "id": "{DEVICE_ID_1}",
            "mac_address": "",
            "name": "USER_ID_DEVICE",
            "owner_id": "{USER_ID}"
        },
        {
            "device_type": "sip_device",
            "enabled": true,
            "hotdesked": true,
            "id": "{DEVICE_ID_2}",
            "mac_address": "",
            "name": "OWNER_ID_DEVICE",
            "owner_id": "{OWNER_ID}"
        }
      ],
     "request_id": "{REQUEST_ID}",
     "revision": "{REVISION}",
     "status": "success"
}

Create an authorization-by-IP device

Creates a device that authenticates by IP address instead of by username and password.

Method and endpoint

PUT /v2/accounts/{ACCOUNT_ID}/devices

Request

    curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{"data":{"enabled":true,"name":"authn_by_ip","sip":{"invite_format":"e164", "ip":"{IP_ADDRESS}","method":"ip"}}}' \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/devices

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": "authn_by_ip",
        "register_overwrite_notify": false,
        "ringtones": {},
        "sip": {
            "invite_format": "e164",
            "ip": "{IP_ADDRESS}",
            "method": "ip",
            "registration_expiration": 300
        },
        "suppress_unregister_notifications": false
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}