Update a Phone

Updates a phone, such as the template, extension binding, and configuration values. All fields are optional, and only the specified fields are updated.

Request URL

PUT {base_url}/uc-cautop/api/v1/phones/{id}

Request parameters

Headers
Parameter Required Type Description
Authorization Yes String The access token used for authentication.

Format: Bearer {access_token}.
x-tenant-code No String The tenant name.
Note: You can obtain tenant name using the Query Tenants interface.
Path parameters
Parameter Required Type Description
id Yes String The phone ID. You can obtain the ID using the Search Phones interface.
Body parameters
Parameter Required Type Description
templateId No String The ID of the configuration template to switch the phone to. You can obtain the ID using the Get Available Phone Templates interface.
firstAuth No Boolean Whether to enable first-time authentication.
hotDesking No Boolean Whether to enable Hot Desking.
emergencyCallerId No String The emergency caller number of the phone.
resellerId No String The ID of the reseller assigned to the phone. If omitted, no change is made. 0 clears the reseller assignment. A positive value assigns the phone to the specified reseller.
tenantCode No String The code of the tenant assigned to the phone. If omitted, the existing value is retained. An empty value clears the tenant assignment. A non-empty value assigns the phone to the specified tenant.
userId No String The ID of the user whose extension is bound to the phone. The extension number is resolved by the system. If omitted, no change is made. 0 unbinds the extension. This parameter is mutually exclusive with accounts.
configJson No String The custom configuration values of the phone in JSON format.
accounts No Array<Account_Binding> The list of handset bindings for DECT phones, which replaces all the existing bindings. The handsets not specified are unbound. This parameter is mutually exclusive with userId.
Account_Binding
Parameter Required Type Description
lineIndex Yes Integer The line index, starting from 1, which corresponds to the physical line number of the phone.
userId Yes String The ID of the user whose extension is bound to the handset. You can obtain the ID using the Get Available Extensions for Phones interface.

Response parameters

Parameter Type Description
requestId String The unique ID of the request, which can be used to quickly locate the request.
code String The HTTP status code of the request.
  • 200: Request succeeded.
  • Non-200 value: Request failed.
message String The status message of the request.
detailMessage String The detailed error information.

When the request is successful, this parameter returns empty.
result Object<Phone> The updated phone.
Phone
Parameter Type Description
id String The unique identifier of the phone.
ownerType String

The owner type of the phone:

  • admin: Administrator.
  • reseller: Reseller.
ownerId String The ID of the owner.
mac String The MAC address of the phone, in the format AA:BB:CC:DD:EE:FF or AA-BB-CC-DD-EE-FF.
vendor String The vendor identifier of the phone, for example Yealink, Fanvil, Grandstream.
model String The model of the phone, for example T54W, X5U.
phoneType String

The device type of the phone:

  • deskphone: Desk phone.
  • conferencephone: Conference phone.
  • dect: DECT wireless phone.
templateId String The ID of the configuration template that the phone uses.
configJson String The custom configuration values of the phone in JSON format, which override the template default values.
firstAuth Boolean Whether first-time authentication is enabled.
hotDesking Boolean Whether Hot Desking is enabled.
emergencyCallerId String The emergency caller number of the phone, which identifies the physical location of the phone for emergency calls.
status String

The registration status of the phone:

  • registered: The phone is registered and online.
  • unregistered: The phone is unregistered or offline.
tenantCode String The code of the associated tenant. An empty value indicates that the phone is not assigned to a tenant.
version Integer The version number for optimistic locking, which increments on each update.
createdAt String The time when the phone was created, in Unix timestamp format (seconds).
updatedAt String The time when the phone was last updated, in Unix timestamp format (seconds).
adminPassword String The administrator password of the phone, which is used to log in to the phone web interface.

Example

Request example

PUT /uc-cautop/api/v1/phones/363526076436074496 HTTP/1.1
Host: api.cn.novoone.com
Authorization: Bearer eyJraWQiOiJjbi0wLWtleS0xIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJkaXN0cmlidXRvcmV4YW1wbGVAb3V0bG9vay5jb20iLCJncmFudF90eXBlIjoib3BlbmFwaSIsImNsaWVudF9leHQiOnsiZGVzY3JpcHRpb24iOiLnrKzkuInmlrnlkIjkvZzkvJnkvLTlupTnlKgiLCJwYXJ0bmVyIjoi56S65L6L5ZCI5L2c5LyZ5Ly0In0sImNsaWVudF90eXBlIjoib3BlbmFwaSIsImV4cCI6MTc5MDc2MTIyMCwiaWF0IjoxNzkwNzM5NjIwLCJqdGkiOiJiOWY2YTllMC1iNzI1LTQ0MWItOWM4MS0xNTViN2I2MzQzZTEiLCJjbGllbnRfaWQiOiJub3ZvLW9wZW4tcGxhdGZvcm0iLCJ1c2VyX2V4dCI6eyJyb2xlSWRzIjpbM10sInN0eXBlIjoiQURNSU4iLCJ0ZW5hbnRDb2RlIjpudWxsLCJ0eXBlIjoiUF9BQ0NPVU5UIiwidXNlcklkIjozMDc2OTEzNjQ0OTE1OTk4NzIwLCJlbWFpbCI6ImRpc3RyaWJ1dG9yZXhhbXBsZUBvdXRsb29rLmNvbSIsInVzZXJuYW1lIjoiZGlzdHJpYnV0b3JleGFtcGxlQG91dGxvb2suY29tIiwidWNJZCI6MzA3NjkxMzY0NDg5MDgzMjg5Nn19.pLZvlI7wJOdlIe2rosP2RgmFghax1RIr5Bx8hM8hNHAcodWeuhl0y6mbm2Rx6HzEIaAqBv51HhtRgJCWUTt8H3Gx7gbGQ-oL-ay5QO8xKWyx9l-o2N9xqoxFnHEVJ1eODMtyZJdi0irq36D95TcDMFLgotKo9TeAr4WrZCelgLyawvyPw8aNpJqNvnc0giI43O8Ov_PjV8VZkQ3UPhWmQEoaLEc1QRCyV546snUuRZd2Ue_wJdW4jHQ5kxSLKq9RXIt-Y3RBweWh4ZALMfSEbOAcg9qzZkA-a_k1c4r2qmYeN1-RS10E7sBmx2KbrQ0JmtfRwzjIfowkZyaIv-5abg
Content-Type: application/json
x-tenant-code: jint
{
  "emergencyCallerId": "911"
}

Response example

HTTP/1.1 200 OK
{
  "requestId": "479be843a5ba3f2136f86bab32e09d56",
  "code": "200",
  "message": "SUCCESS",
  "detailMessage": "",
  "result": {
    "id": "363526076436074496",
    "ownerType": "admin",
    "ownerId": "3076913644915998720",
    "mac": "AA:BB:99:78:79:0D",
    "vendor": "Fanvil",
    "model": "A10",
    "phoneType": "deskphone",
    "templateId": "315428389935468544",
    "configJson": "{\"var_password\": \"A60SzVZgII\", \"user_password\": \"lTfXLIMLI7\", \"phone_password\": \"BFZ2RO0vlm\"}",
    "firstAuth": false,
    "hotDesking": true,
    "emergencyCallerId": "911",
    "status": "unregistered",
    "tenantCode": "jint",
    "version": 1,
    "createdAt": "1790738570",
    "updatedAt": "1790738571",
    "adminPassword": "BFZ2RO0vlm"
  }
}