API Version: Development

Handset Management

Permissions

Unless otherwise specified, this requires System-Admin or Company-Admin access.

command 'create'

Path: /rest/dialplan/create/ 6.3.10+

This option requires System-Admin access.

Create a very basic phone entry where auto provisioning is not possible or desired. The device will be created already activated.

{
    "type": "phone"
    "values": {
        "mac": "device MAC",
        "phoneid": "phone id (optional, used if mac empty)",
        "name": "optional name",
        "company": "company",
        "phone_type": "phone-type"
    }
}

Return value:

{
    "result": "success",
    "numrows": rows-created
}

At the time of writing, the valid list of phone types is as follows (See also the readtypes handset provisioning call):

Cisco7941 Cisco7961 Cisco7965 a580ip aastra480i aastra51i aastra53i aastra53i-1line aastra53i536m aastra53i536m2 aastra53i536m3 aastra55i aastra55i-1l536m aastra55i-1l560m aastra55i-1line aastra55i536m aastra55i536m2 aastra55i536m3 aastra55i560m aastra57i aastra57i-1l536m aastra57i-1l560m aastra57i-1line aastra57i536m aastra57i536m2 aastra57i536m3 aastra57i560m aastra57i560m2 aastra57i560m3 aastra6730i aastra6731i aastra9112i aastra9133i basic_soft bria c460ip cp7811 cp7821 cp7821-1 cp7841 cp7841-1 cp7841-2 cp7861 cp7861-1 cp7861-2 eyebeam generic ip320 ip320_msg ip321 ip321_msg ip330 ip330_msg ip331 ip331_msg ip335 ip335_msg ip4000 ip430 ip430-1 ip450 ip450-1 ip5000 ip501 ip501-1 ip550 ip550-1 ip560 ip560-1 ip6000 ip601 ip601-1 ip601-2 ip601-3 ip601-4 ip650 ip650-1 ip650-2 ip650-3 ip650-4 ip670 ip670-1 ip670-2 ip670-3 ip670-4 ip7000 ip840c ip840c-1 ip840c-111 ip840c-12 ip840c-156 ip840c-2 ip840c-210 ip840c-336 ip840c-606 ip840cs ip840cs-12 kws300 n300ip n300ip-1 n510ip n510ip-1 n720ip n720ip100 n720ip25 n720ip50 n720ip75 newYeaVP2009 pap2t s450ip s685ip snom190 snom190-1 snom300 snom300-hold snom320 snom320-1 snom320-111 snom320-12 snom320-156 snom320-2 snom320-210 snom320-3 snom320-336 snom320-606 snom320s snom320s-12 snom360 snom360-1 snom360-111 snom360-12 snom360-156 snom360-2 snom360-210 snom360-3 snom360-336 snom360-606 snom360s snom360s-12 snom370 snom370-1 snom370-111 snom370-12 snom370-156 snom370-2 snom370-210 snom370-336 snom370-606 snom370s snom370s-12 snom710 snom710-1 snom710-4 snom715 snom715-1 snom715-4 snom720 snom720-1 snom725 snom725-1 snom760 snom760-1 snom820 snom820-1 snom820-10 snom821 snom821-1 snom821-10 snom870 snom870-1 snom870-10 snom870-6 snomD305 snomD315 snomD345 snomD375 snomMP snomPA1 snomm3 snomm3-1 snomm9 spa1001 spa112 spa2000 spa2002 spa2102 spa301 spa303 spa502g spa504g spa504g-1 spa508g spa508g-1 spa509g spa509g-1 spa525g spa525g-1 spa8000 spa841 spa901 spa921 spa922 spa941 spa942 spa962 tgp500 tgp500-1 tls_soft trio8500 trio8800 vvx101 vvx101-1-0 vvx1500 vvx1500-1 vvx201 vvx201-1 vvx201-1-0 vvx300 vvx300-1 vvx300-1-0 vvx300-15 vvx300-6 vvx310 vvx310-1 vvx310-1-0 vvx310-15 vvx310-6 vvx400 vvx400-1 vvx400-1-0 vvx400-111 vvx400-12 vvx400-3 vvx410 vvx410-1 vvx410-1-0 vvx410-111 vvx410-12 vvx410-3 vvx500 vvx500-1 vvx500-1-0 vvx500-12 vvx500-12s vvx500-1s vvx500s vvx500v vvx500v-1 vvx500v-1-0 vvx500v-12 vvx500v-12s vvx500v-1s vvx500vs vvx600 vvx600-1 vvx600-1-0 vvx600-12 vvx600-12s vvx600-1s vvx600s vvx600v vvx600v-1 vvx600v-1-0 vvx600v-12 vvx600v-12s vvx600v-1s vvx600vs webrtc xlite yealinkCP860 yealinkCP920 yealinkCP960 yealinkT18 yealinkT19 yealinkT20 yealinkT20-1 yealinkT21 yealinkT21-1 yealinkT22 yealinkT22-1 yealinkT23 yealinkT23-1 yealinkT26 yealinkT26-1 yealinkT26-exp39 yealinkT261exp39 yealinkT26L yealinkT26Lexp39 yealinkT26l yealinkT26lexp39 yealinkT27 yealinkT27-1 yealinkT27-exp20 yealinkT27l1 yealinkT27lexp20 yealinkT28 yealinkT28-1 yealinkT28-exp39 yealinkT281exp39 yealinkT28L yealinkT28Lexp39 yealinkT28l yealinkT28lexp39 yealinkT29 yealinkT29-1 yealinkT29-exp20 yealinkT29l1 yealinkT29lexp20 yealinkT32 yealinkT32-1 yealinkT38 yealinkT38-1 yealinkT38-exp39 yealinkT381exp39 yealinkT38L yealinkT38Lexp39 yealinkT38l yealinkT38lexp39 yealinkT40 yealinkT40-1 yealinkT41 yealinkT41-1 yealinkT41-6 yealinkT41l1 yealinkT42 yealinkT42-1 yealinkT42-6 yealinkT42l1 yealinkT46 yealinkT46-1 yealinkT46-10 yealinkT46-10e40 yealinkT46-exp40 yealinkT461exp40 yealinkT46L yealinkT46Lexp40 yealinkT46l yealinkT46lexp40 yealinkT48 yealinkT48-1 yealinkT48-12 yealinkT48-12e40 yealinkT48-exp40 yealinkT481exp40 yealinkT48_1 yealinkT48_exp40 yealinkT49 yealinkT49-1 yealinkT49-12 yealinkT49-12e40 yealinkT49-exp40 yealinkT491exp40 yealinkT49_1 yealinkT49_exp40 yealinkT52 yealinkT52-1 yealinkT52-8 yealinkT52l1 yealinkT54 yealinkT54-1 yealinkT54-10 yealinkT54l1 yealinkT56 yealinkT56-1 yealinkT56-12 yealinkT56-12e50 yealinkT56-exp50 yealinkT561exp50 yealinkT56_1 yealinkT56_exp50 yealinkT58 yealinkT58-1 yealinkT58-12 yealinkT58-12e50 yealinkT58-exp50 yealinkT581exp50 yealinkT58_1 yealinkT58_exp50 yealinkVP2009 yealinkVP530 yealinkVP530-1 yealinkW52 yealinkW52-1 yealinkW60 yealinkW60-1 zoiper

command 'read'

Path: /rest/dialplan/read/ 6.3.10+

This option requires System-Admin or relevant Company-Admin access.

Read detailed information/settings about a specific handset. Query is by mac address, mac and port, or by phoneid (mac and port together)

{
    "type": "phone"
    "scope": {
        "mac": "device MAC",
        "port": "device port (optional)",
        "phoneid": "phone id (optional, used if mac empty)",
    }
}

Return value:

{
    "result": "success",
    "values": [
        {
            "mac": "device mac",
            "port": port-num,
            "name": "devicename",
            "company": "company",
            "phone_type": "phone_type (see above)",
            "zone": "Time Zone or empty string",
            "can_hotdesk": BOOL,
            "can_forward": BOOL,
            "qualify": BOOL or empty string,
            "call_group": "call group ID or null",
            "access": "access level",
            "nat_mode": BOOL,
            "nat_ipaddr": "NAT IP address type",
            "ntp": "NTP server type",
            "codec_list": "preferred codecs",
            "barge": barge/bargeable mode,
            "ip_addr": "null or fixed IP/mask",
            "ip_dns1": "null or fixed DNS server",
            "ip_dns2": "null or fixed DNS server",
            "ip_gateway": "null or fixed gateway IP",
            "ip_domain": "null or fixed search domain"
        },
        ...
    ]
}

The barge field is a bitfield:

#define CAN_BARGE       1
#define CAN_BE_BARGED   2

so to set bargeable and can barge, the value will be 3, or to disable both, set 0.

At the time of writing, the valid list of time zones are as follows:

Atlantic/Cape_Verde Atlantic/Bermuda Europe/London Europe/Paris Europe/Helsinki Africa/Nairobi Europe/Nicosia Asia/Hong_Kong US/Alaska US/Pacific US/Mountain US/Central US/Eastern

command 'update'

Path: /rest/dialplan/update/ 6.3.10+

This option requires System-Admin or relevant Company-Admin access.

Update detailed information/settings about a specific handset. Query is by mac address, mac and port, or by phoneid (mac and port together)

The company field cannot be edited and must be changed using the assign call (See handset provisioning page). Unchanged fields may be left undefined, but if setting a field starting ip_ then all such fields must be set together.

If the phone_type field is modified, and results in a change in the number of "ports" that a device has, then the relevant rows will be created or deleted with some reasonable defaults - It is suggested that these records are queried and corrected to verify that the defaults are suitable.

{
    "type": "phone"
    "scope": {
        "mac": "device MAC",
        "port": "device port",
        "phoneid": "phone id (optional, used if mac empty)",
    },
    "values": {
        "name": "devicename",
        "phone_type": "phone_type (see above)",
        "zone": "Time Zone or empty string (see above)",
        "can_hotdesk": BOOL,
        "can_forward": BOOL,
        "qualify": BOOL or empty string,
        "call_group": "call group ID or null",
        "access": "access level",
        "nat_mode": BOOL,
        "nat_ipaddr": "NAT IP address type",
        "ntp": "NTP server type",
        "codec_list": "preferred codecs",
        "barge": barge/bargeable mode,
        "ip_addr": "null or fixed IP/mask",
        "ip_dns1": "null or fixed DNS server",
        "ip_dns2": "null or fixed DNS server",
        "ip_gateway": "null or fixed gateway IP",
        "ip_domain": "null or fixed search domain"
    }
}

Return value:

{
    "result": "success",
    "numrows": 1
}

command 'delete'

Path: /rest/dialplan/delete/ 6.3.10+

This option requires System-Admin access.

Deletes an active phone from the system completely.

{
    "type": "phone"
    "scope": {
        "mac": "device MAC",
        "phoneid": "phone id (optional, used if mac empty)",
    }
}

Return value:

{
    "result": "success",
    "numrows": rows-deleted
}

command 'reboot'

Path: /rest/dialplan/reboot/ 6.3.10+

This option allows System-Admin and Company-Admin users to reboot phones in their administered companies.

Requests a reboot of the specified device.

{
    "type": "phone"
    "scope": {
        "mac": "device MAC",
        "phoneid": "phone id (optional, used if mac empty)",
    }
}

Return value:

{
    "result": "success",
    "numrows": rows-matched,
    "company": "company of matched device"
}

command 'newpass'

Path: /rest/dialplan/newpass/ 6.3.10+

This option allows System-Admin and Company-Admin users to randomise phone passwords in their administered companies.

Requests new SIP passwords for the selected device. All ports will be updated. There may be a short delay before this update reaches the active configuration.

{
    "type": "phone"
    "scope": {
        "mac": "device MAC",
        "phoneid": "phone id (optional, used if mac empty)",
    }
}

Return value:

{
    "result": "success",
    "numrows": rows-updated,
    "company": {
        port-num: "company of matched device"
        ...
    }
}