Search Phones

Search phones in a tenant.

Request URL

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

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
pageSize	Yes	Integer	The number of records to retrieve per page.
pageNumber	Yes	Integer	The page number to retrieve.
keyword	No	String	The keyword used to search for phones. The keyword fuzzy matches the MAC address, vendor, model, tenant code, extension number, IP address, reseller email, owner email, or template name.
sorts	No	Array<Sort_Condition>	The sort conditions. If omitted, the result is sorted by creation time in descending order.

Sort_Condition


Parameter	Required	Type	Description
property	No	String	The name of the field to sort by. - `vendor` - `model` - `mac` - `privateIp` - `firmware` - `tenantCode` - `createdAt` - `extension`
direction	No	String	The sort order: - asc: Sort in ascending order. - desc: Sort in descending order.

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<Search_Result>	The search result of phones.

Search_Result


Parameter	Type	Description
pageSize	Integer	The number of records per page.
pageNumber	Integer	The current page number.
count	String	The total number of matching records.
results	Array<Phone>	The list of matching phones.

Phone


Parameter	Type	Description
id	String	The unique identifier of the phone.
mac	String	The MAC address of the phone.
vendor	String	The vendor identifier of the phone.
model	String	The model of the phone.
status	String	The registration status of the phone: - registered: The phone is registered and online. - unregistered: The phone is unregistered or offline.
extension	String	The extension number currently bound to the phone. This parameter is returned only when the phone is bound to an extension.
adminPassword	String	The administrator password of the phone, which is used to log in to the phone web interface.
templateName	String	The name of the associated configuration template.
firstAuth	Boolean	Whether first-time authentication is enabled.
hotDesking	Boolean	Whether Hot Desking is enabled.
createdAt	String	The time when the phone was created, in Unix timestamp format (seconds).
phoneType	String	The device type of the phone: - deskphone: Desk phone. - conferencephone: Conference phone. - dect: DECT wireless phone.
ownerType	String	The owner type of the phone: - admin: Administrator. - reseller: Reseller.
ownerId	String	The ID of the owner.
tenantCode	String	The code of the associated tenant. An empty value indicates that the phone is not assigned to a tenant.
hotDeskingStatus	String	The Hot Desking status of the phone: - guest_in: A guest is logged in. - guest_out: The guest is logged out. This parameter is returned only when `hotDesking` is `true`.
handsets	Array<Handset>	The list of DECT handsets. This parameter is returned only for DECT phones, and contains only the handsets bound to extensions.
handsetTotal	Integer	The total number of DECT handsets, which is defined in the associated template.
ownerDisplay	String	The display name of the owner. This parameter is empty if the query fails.
resellerDisplay	String	The display name of the reseller. This parameter is empty if the phone has no reseller or the query fails.
templateId	String	The ID of the configuration template associated with the phone.
ownerEmail	String	The email address of the owner. This parameter is empty if the query fails.
userId	String	The ID of the currently bound user. This parameter is returned only when the phone is bound to an extension.
firstName	String	The first name of the extension user. This parameter is returned only when the phone is bound to an extension.
lastName	String	The last name of the extension user. This parameter is returned only when the phone is bound to an extension.

Handset


Parameter	Type	Description
handset	Integer	The handset number, starting from 1, which corresponds to the line index of the phone.
status	String	The registration status of the handset: - registered: The handset is registered. - unregistered: The handset is unregistered. - `-`: The handset is not bound to an extension.
user	String	The extension number bound to the handset. This parameter is empty when the handset is not bound.
firstName	String	The first name of the bound user. This parameter is empty when the name is not set or the query fails.
lastName	String	The last name of the bound user. This parameter is empty when the name is not set or the query fails.

Example

Request example

POST /uc-cautop/api/v1/phones/search-page 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
{
  "pageNumber": 1,
  "pageSize": 5,
  "keyword": "AA:BB:99:78:79:0D"
}

Response example

HTTP/1.1 200 OK
{
  "requestId": "2a93bb4684ad9395b684600d8069eaad",
  "code": "200",
  "message": "SUCCESS",
  "detailMessage": "",
  "result": {
    "pageSize": 5,
    "pageNumber": 1,
    "count": "1",
    "results": [
      {
        "id": "363526076436074496",
        "mac": "AA:BB:99:78:79:0D",
        "vendor": "Fanvil",
        "model": "A10",
        "status": "unregistered",
        "adminPassword": "BFZ2RO0vlm",
        "templateName": "YSDP_Fanvili10S",
        "firstAuth": false,
        "hotDesking": true,
        "createdAt": "1790738570",
        "phoneType": "deskphone",
        "ownerType": "admin",
        "ownerId": "3076913644915998720",
        "tenantCode": "jint",
        "hotDeskingStatus": "guest_out",
        "handsets": [],
        "handsetTotal": 0,
        "ownerDisplay": "Service Provider",
        "resellerDisplay": "",
        "templateId": "315428389935468544",
        "ownerEmail": "distributorexample@outlook.com"
      }
    ]
  }
}