Create phone configuration

POST

/domains/{domain}/phoneconfiguration

Last modified:2026-10-09 00:49:06

OperationId:CreatePhoneConfigurationSpecificMacAddress

Creates the button layout for one phone, identified by its MAC address, in the domain. It has the same fields as a phone template, and is often a copy of one.

phoneconfiguration-mac-address is required: 12 hexadecimal digits with no separators, such as 00005E005301. A phone that already has a configuration in the domain returns 409.

Every button you send is saved, and the buttons belong to this configuration in this domain only. The button types and features a model supports come from GET /deviceprofiles/{brand}/{model}, in devicemodel.

Two button features also write a dial rule. It goes in the dial plan of the user on the first line button, or in the domain's dial plan when there is no line button. A queue_status button toggles the user's call queue availability: its target is ignored, and reads return it empty. A timeframe_status button toggles a time frame: its target is the time frame name, and Default means the default time frame. Add targetUser to the button's phoneconfiguration-extra to toggle another user's time frame. The dial rules appear with the dial plan's other dial rules.

phoneconfiguration-domain in the body is ignored: the domain comes from the path. A 202 means the change is accepted and already applied.

Requires Office Manager scope or above for your own domain, Reseller scope for the domains in your territory, or Super User scope.

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Path Params

Body Params application/json

Examples

Responses

🟢202Accepted

application/json

The change is accepted and already applied.

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠404Not Found

🟠409Conflict

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://awqacore01.crexendocloud.com/ns-api/v2/domains//phoneconfiguration' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "phoneconfiguration-mac-address": "00005E005301",
    "phoneconfiguration-description": "Front desk phone",
    "phoneconfiguration-brand": "Grandstream",
    "phoneconfiguration-model": "WP826",
    "phoneconfiguration-buttons": [
        {
            "phoneconfiguration-button-order": 1,
            "phoneconfiguration-button-type": "line_only",
            "phoneconfiguration-button-feature": "line",
            "phoneconfiguration-button-target": "1001",
            "phoneconfiguration-button-label": "Line 1",
            "phoneconfiguration-button-locked": 0,
            "phoneconfiguration-extra": {}
        },
        {
            "phoneconfiguration-button-order": 2,
            "phoneconfiguration-button-type": "line_only",
            "phoneconfiguration-button-feature": "line",
            "phoneconfiguration-button-target": "1001",
            "phoneconfiguration-button-label": "Line 2",
            "phoneconfiguration-button-locked": 0,
            "phoneconfiguration-extra": {}
        },
        {
            "phoneconfiguration-button-order": 4,
            "phoneconfiguration-button-type": "mpk",
            "phoneconfiguration-button-feature": "queue_status",
            "phoneconfiguration-button-target": "",
            "phoneconfiguration-button-label": "Queue",
            "phoneconfiguration-button-locked": 1,
            "phoneconfiguration-extra": {}
        }
    ]
}'

Response Example

202 - Accepted

{
    "code": 202,
    "message": "Accepted"
}

Modified at 2026-10-09 00:49:06

Read phone configuration

Update phone configuration