API Version: 6.5

Phone Provisioning

Permissions

Unless otherwise specified, this requires System-Admin or Company-Admin with 'default' company access. If promoting a phone to a non-default company, a Company-Admin also needs access to the target company.

command 'inactive'

Path: /rest/dialplan/inactive/
List all phones which have requested provisioning, but have an outstanding activation step pending. No filtering is possible on this query.
{
    "type": "phone"
}
Return value:
NOTE: phone_type is only present from 6.3.10+
{
    "result": "success",
    "values": [
        {
            "phoneid": "phone id",
            "phone_type": "phone type",
            "type": "phone type description",
            "created": creation epoch-time
        }
    ],
    "numrows": rows-returned
}
Note that the phoneid value is the handset identifier which is it's mac address and it's 'port' number combined. For most devices, the port number is a 0.

command 'active'

Path: /rest/dialplan/active/ 6.3.10+
List all phones which have been added or promoted to active. The query may optionally be filitered using a company-id.
{
    "type": "phone"
    "scope": {
        "company": "company or list of companies (optional)"
    },
}
Return value:
{
    "result": "success",
    "values": [
        {
            "phoneid": "phone id",
            "phone_type": "phone type",
            "type": "phone type description",
            "created": creation epoch-time,
            "company": "company"
        }
    ],
    "numrows": rows-returned
}
Note that the phoneid value is the handset identifier which is it's mac address and it's 'port' number combined. For most devices, the port number is a 0.

command 'promote'

Path: /rest/dialplan/promote/
Promote a phone from the inactive list into the active phones list. A multi-port device will have all ports activated. An OPTIONAL company value can be specified to promote and assign the handset in one operation. If omitted, the device is promoted into the default company. The user must have permission, and the company must exist.
{
    "type": "phone",
    "scope": {
        "phoneid": "0123456789ab0"
    },
    "values": {
        "company": "acompany"
    }
}
Return value:
{
    "result": "success",
    "numrows": rows-updated
}

command 'demote'

Path: /rest/dialplan/demote/
Demote a phone from the inactive list, effectively deleting it. A multi-port device will have all ports deleted.
{
    "type": "phone",
    "scope": {
        "phoneid": "0123456789ab0"
    }
}
Return value:
{
    "result": "success",
    "numrows": rows-removed
}

command 'assign'

Path: /rest/dialplan/assign/ 6.3.10+
This option allows System-Admin users to reassign a phone to a new company.
{
    "type": "phone"
    "scope": {
        "mac":"device MAC",
        "phoneid": "phone id (optional, used if mac empty)",
        "port":"port for multiport device (zero based)",
        "company":"source company for verification"
    },
    "values": {
        "company":"target company"
    }
}
Return value:
{
    "result": "success",
    "numrows": rows-updated,
    "company": {
        port-num: "company of matched device"
        ...
    }
}

command 'readtypes'

Path: /rest/dialplan/readtypes/ 6.3.10+
This option allows System-Admin and Company-Admin users to list all valid phone type values, including all variants.
{
    "type": "phone"
}
Return value:
{
    "result": "success",
    "numrows": number of rows,
    "values": [
        {
            "phone_type": "phone-type-key",
            "pgroup": "Phone's group",
            "description": "Long description"
        },
        ...
    ]
}