Add a Phone

Adds a phone by registering its MAC address, and optionally binds extensions to it.

Request URL

POST {base_url}/uc-cautop/api/v1/phones

Request parameters

Headers


Parameter	Required	Type	Description
Authorization	Yes	String	The access token used for authentication. Format: Bearer `{access_token}`.
x-tenant-code	Yes	String	The tenant name. Note: You can obtain tenant name using the Query Tenants interface.

Body parameters


Parameter	Required	Type	Description
vendor	Yes	String	The vendor identifier of the phone, for example `Yealink`, `Fanvil`, `Grandstream`.
model	Yes	String	The model of the phone, for example `T54W`, `X5U`.
mac	Yes	String	The MAC address of the phone, in the format `AA:BB:CC:DD:EE:FF` or `AA-BB-CC-DD-EE-FF`. The MAC address must be unique under the same administrator.
templateId	Yes	String	The ID of the configuration template that the phone uses. You can obtain the ID using the Get Available Phone Templates interface.
firstAuth	No	Boolean	Whether to enable first-time authentication. If enabled, the phone needs authentication when it connects for the first time.
hotDesking	No	Boolean	Whether to enable Hot Desking. If enabled, users can temporarily log in to their extensions on the phone.
emergencyCallerId	No	String	The emergency caller number of the phone, which identifies the physical location of the phone for emergency calls. This parameter can be set only when `hotDesking` is `true`.
resellerId	No	String	The ID of the reseller that the phone is assigned to. If omitted, the phone is not assigned to a reseller.
tenantCode	No	String	The code of the tenant that the phone is assigned to. If omitted, the phone is not assigned to a tenant. In a tenant context, the phone is automatically assigned to the current tenant.
userId	No	String	The ID of the user whose extension is bound to Line 1 of the phone. The extension number is resolved by the system. If omitted, no extension is bound. This parameter is mutually exclusive with `accounts`. You can obtain the ID using the Get Available Extensions for Phones interface.
accounts	No	Array<Account_Binding>	The list of handset bindings for DECT phones. Only specify the handsets with bound extensions. This parameter is mutually exclusive with `userId`.
configJson	No	String	The custom configuration values of the phone in JSON format, which override the template default values.

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_ID>	The ID of the created phone.

Phone_ID


Parameter	Type	Description
id	String	The ID of the created phone.

Example

Request example

POST /uc-cautop/api/v1/phones 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
{
  "vendor": "Fanvil",
  "model": "A10",
  "mac": "AA:BB:99:78:79:0D",
  "templateId": "315428389935468544",
  "hotDesking": true,
  "emergencyCallerId": "911"
}

Response example

HTTP/1.1 200 OK
{
  "requestId": "af3576080ded48beb6476198718283d1",
  "code": "200",
  "message": "SUCCESS",
  "detailMessage": "",
  "result": {
    "id": "363526076436074496"
  }
}