# Open API for Yealink Management Cloud Service V4X.pdf - Pages 21-40

**Source:** Open API for Yealink Management Cloud Service V4X.pdf
**Pages:** 21-40 of 164
**Chunk:** 2

---

Open API for Yealink Management Cloud Service V4X



 limit                Long                 The maximum returned number.
 total                Long                 The total number.
 data                 Device[]             Device information array

Device object definition

 Paramete         Data       Description
 r                Type
 id               Strin      device id
                  g
 mac              Strin      Device MAC
                  g
 sn               Strin      Device SN
                  g
 name             Strin      Device Name
                  g
 modelId          Strin      Model ID
                  g
 siteId           Strin      Site ID
                  g
 programV         Strin      Device firmware version number
 ersion           g
 deviceSta        Strin      Device status, online: online, offline: offline, pending:
 tus              g          not reported

Example Request

  httpPOST /v2/dm/listDevices HTTP/1.1
  Host: api.ymcs.yealink.com
  Content-Type: application/json

  {
  "skip": 0,
  "limit": 20,
  "autoCount": true,
  "filter":{
  "deviceStatus":1,

                                                                                     21 / 164
Open API for Yealink Management Cloud Service V4X


  "siteId":"a624453e1cbb44ecb9bb6ee31731a856"
  }
  }


Example Response

  httpHTTP/1.1 200
  Content-Type: application/json;charset=UTF-8

  {
  "skip": 0,
  "limit": 10,
  "total": 1,
  "data":[{
  "id": "8d07a56207074d26b61026099625b9e2",
  "mac":"001565bbb1a9",
  "sn":"1106312113402006",
  "name":"my t54s",
  "modelId":"61e659e4d78d42ebada88ef1eb751b64",
  "siteId":"a624453e1cbb44ecb9bb6ee31731a856",
  "programVersion":"70.83.0.68",
  "deviceStatus":"online"
  }]
  }


2.1.7 Edit Device
Request Method
PATCH
Request URL
/v2/dm/devices/{deviceId}
Path parameter

 parameter           Data Type           Required        Description
 deviceId            String              Yes             The device ID address.

Body parameter

 Paramete         Data             Require          Description
 r                Type             d

                                                                                  22 / 164
Open API for Yealink Management Cloud Service V4X



 name             String           No               Device name, maximum length 128
 siteId           String           No               Site ID

HTTP status code

 Code                Description
 204                 Operation successful
 400                 Client parameter exception
 401                 Authentication failed
 500                 Server exception

Example Request

  httpPATCH /v2/dm/devices/8d07a56207074d26b61026099625b9e2 HTTP/1.1
  Host: api.ymcs.yealink.com
  Content-Type: application/json

  {
  "name":"my t54s2"
  }


Example Response

  httpHTTP/1.1 204


2.1.8 Device Details
Request Method
GET
Request URL
/v2/dm/devices/{deviceId}
Path parameter

 parameter               Data Type              Required        Description
 deviceId                String                 Yes             The device ID.

HTTP status code


                                                                                      23 / 164
Open API for Yealink Management Cloud Service V4X



 Code                Description
 200                 Operation successful
 400                 Client parameter exception
 401                 Authentication failed
 500                 Server exception

Response parameters

 Paramet         Data            Description
 er              Type
 id              String          device id
 mac             String          Device MAC
 sn              String          group id
 name            String          Device Name
 modelId         String          Model ID
 modelN          String          Model Name
 ame
 siteId          String          Site ID
 siteNam         String          Site Name
 e
 lanIp           String          Intranet IP
 deviceSt        String          Device status, online: online, offline: offline,
 atus                            pending: not reported
 programV String                 Firmware version
 ersion
 lastRepo        long            Last reporting time
 rtTime
 accounts        ReportAcc       Reported account information
                 ount[]

ReportAccount object definition

 Paramet          Data        Description
 er               Type

                                                                                    24 / 164
Open API for Yealink Management Cloud Service V4X



 accountI         String      Account ID
 d
 lineId           Intege      Account line, starting from 1
                  r
 accountT         Intege      Account type: 0: SIP, 1: H323, 2: SFB
 ype              r
 accountS         String      Account server address
 erver
 register         String      Registration Name
 Name
 usernam          String      User Name
 e
 status           Intege      Account status: 1: Registered 2: dnd 3: Not registered 4:
                  r           Unknown

Example Request

  httpGET /v2/dm/devices/8d07a56207074d26b61026099625b9e2 HTTP/1.1
  Host: api.ymcs.yealink.com


Example Response

  httpHTTP/1.1 200
  Content-Type: application/json;charset=UTF-8

  {
  "id": "8d07a56207074d26b61026099625b9e2",
  "mac":"001565bbb1a9",
  "sn":"1106312113402006",
  "name":"my t54s",
  "modelId":"61e659e4d78d42ebada88ef1eb751b64",
  "modelName":"SIP-T54S",
  "siteId":"a624453e1cbb44ecb9bb6ee31731a856",
  "siteName":"mysite",
  "lanIp":"10.50.198.6",
  "deviceStatus":"online",
  "programVersion":"70.83.0.68",
  "lastReportTime":1711093807136,
  "accounts":[{
                                                                                    25 / 164
Open API for Yealink Management Cloud Service V4X


  "accountId":"604e67944c7c43fe8b66099254ec3439"
  "lineId":1,
  "accountType":0,
  "accountServer":"10.200.108.48",
  "registerName":"1000",
  "username":"1000",
  "status":0

  },{
  "accountId":"a45a6b4a7e0447b8a6c3f2839d902acd"
  "lineId":2,
  "accountType":0,
  "accountServer":"10.200.108.48",
  "registerName":"2000",
  "username":"2000",
  "status":0
  }]
  }


2.1.9 Device Combination Configuration Query
Request Method
GET
Request URL
/v2/dm/devices/{deviceId}/configs
Path parameter

 parameter               Data Type              Required   Description
 deviceId                String                 Yes        The device ID.

HTTP status code

 Code                Description
 200                 Operation successful
 400                 Client parameter exception
 401                 Authentication failed
 500                 Server exception

Response parameters

                                                                            26 / 164
Open API for Yealink Management Cloud Service V4X



 Parameter               Data             Description
                         Type
 deviceConfig            String           Device MAC Configuration
 siteConfig              String           Device Site Configuration
 globalConfig            String           Enterprise Configurations
 enforceConfig           String           Site forced inheritance configuration

Example Request

  httpGET /v2/dm/devices/8d07a56207074d26b61026099625b9e2/configs HTTP/1.1
  Host: api.ymcs.yealink.com


Example Response

  httpHTTP/1.1 200
  Content-Type: application/json;charset=UTF-8

  {
  "deviceConfig": "account.1.auth_name = test1101",
  "siteConfig":"lang.gui=English",
  "globalConfig":"auto_provision.server.url=\r\nlang.gui=English",
  "enforceConfig":"security.user_password=user2"
  }


2.2 Device Group Management
2.2.1 Add Group
Request Method
POST
Request URL
/v2/dm/deviceGroups
Body parameter

 Paramete         Data          Requi        Description
 r                Type          red
 name             String        Yes          Group name, length 64
 deviceTyp        Integer       Yes          Device Type 1: Phone Device 3: Room
                                                                                   27 / 164
Open API for Yealink Management Cloud Service V4X



 e                                           Device
 Descripti        String        No           Group Description information, length 256
 on

HTTP status code

 Code                Description
 201                 Operation successful
 400                 Client parameter exception
 401                 Authentication failed
 500                 Server exception

Response parameters

 Parameter               Data Type           Description
 id                      String              The group ID.
 name                    String              Group Name
 deviceType              Integer             Device Types
 description             String              Group description information

Example Request

  httpPOST /v2/dm/deviceGroups HTTP/1.1
  Host: api.ymcs.yealink.com
  Content-Type: application/json

  {
  "name":"t54sgroup",
  "deviceType":1,
  "Description":"test"

  }


Example Response

  httpHTTP/1.1 201 Created
  Content-Type: application/json;charset=UTF-8



                                                                                   28 / 164
Open API for Yealink Management Cloud Service V4X


  {
  "id": "00884cef841e48f4acd213c084e65f67",
  "name":"t54sgroup",
  "deviceType":1,
  "Description":"test"
  }


2.2.2 Edit Group
Request Method
PATCH
Request URL
/v2/dm/deviceGroups/{deviceGroupId}
Path parameter

 parameter                        Data Type          Required        Description
 deviceGroupId                    String             Yes             Group ID

Body parameter

 Paramete         Data          Requi        Description
 r                Type          red
 name             String        Yes          Group name, length 64
 deviceTyp        Integer       Yes          Device Type 1: Phone Device 3: Room
 e                                           Device
 Descripti        String        No           Group Description information, length 256
 on

HTTP status code

 Code                Description
 204                 Operation successful
 400                 Client parameter exception
 401                 Authentication failed
 500                 Server exception

Example Request

                                                                                   29 / 164
Open API for Yealink Management Cloud Service V4X


  httpPATCH /v2/dm/deviceGroups/00884cef841e48f4acd213c084e65f67/1.1
  Host: api.ymcs.yealink.com
  Content-Type: application/json

  {
  "name":"t54sgroup2",
  "deviceType":1,
  "Description":"test2"

  }


Example Response

  httpHTTP/1.1 204


2.2.3 Group List
Request Method
POST
Request URL
/v2/dm/listDeviceGroups
Body parameter

 Param        Data           Requir       Description
 eter         Type           ed
 skip         Long           No           Number of skipped records, default is 0
 limit        Long           No           Maximum number of records to retrieve,
                                          default is 10, maximum is 500.
 autoCo       Boolean        No           Whether to respond with the total count, it is
 unt                                      recommended to set it to true when querying
                                          the first page, and pass false for subsequent
                                          page turns.
 filter       Filter         No           search parameters

Filter object definition

 Para       Data       Req    Description
 mete                  uir

                                                                                    30 / 164
Open API for Yealink Management Cloud Service V4X



 r          Typ      ed
            e
 devi       Inte     No        Device type status, 1: Phone Device 3: Room Device, if
 ceTy       ger                not filled in, it means all.
 pe

HTTP status code

 Code                Description
 200                 Operation successful
 400                 Client parameter exception
 401                 Authentication failed
 500                 Server exception

Response parameters

 Parameter          Data Type                  Description
 skip               Long                       offset
 limit              Long                       The maximum returned number.
 total              Long                       Total quantity
 data               DeviceGroup[]              DeviceGroup information array

DeviceGroup object definition

 Parameter           Data            Description
                     Type
 id                  String          Group ID
 name                String          Group name, length 64
 deviceType          Integer         Device Type 1: Phone Device 3: Room Device
 Description         String          Group Description information, length 256

Example Request

  httpPOST /v2/dm/listDeviceGroups HTTP/1.1
  Host: api.ymcs.yealink.com
  Content-Type: application/json


                                                                                   31 / 164
Open API for Yealink Management Cloud Service V4X


  {
  "skip": 0,
  "limit": 10,
  "autoCount": true,
  "filter":{
  "deviceType":1
  }
  }


Example Response

  httpHTTP/1.1 200
  Content-Type: application/json;charset=UTF-8

  {
  "skip": 0,
  "limit": 10,
  "total": 1,
  "data":[{
  "id": "00884cef841e48f4acd213c084e65f67",
  "name":"t54sgroup",
  "deviceType":1,
  "Description":"test"
  }]
  }


2.2.4 Delete Group
Request Method
DELETE
Request URL
/v2/dm/deviceGroups/{deviceGroupId}
PATH parameter

 parameter                        Data Type         Required   Description
 deviceGroupId                    String            Yes        Group ID

HTTP status code

 Code                Description

                                                                             32 / 164
Open API for Yealink Management Cloud Service V4X



 204                 Operation successful
 400                 Client parameter exception
 401                 Authentication failed
 500                 Server exception

Example Request

  httpDELETE /v2/dm/deviceGroups/00884cef841e48f4acd213c084e65f67 HTTP/1.1
  Host: api.ymcs.yealink.com


Example Response

  httpHTTP/1.1 204


2.2.5 Add Device to Group
Request Method
POST
Request URL
/v2/dm/deviceGroups/{deviceGroupId}/addDevices
PATH parameter

 parameter                        Data Type              Required         Description
 deviceGroupId                    String                 Yes              Group ID

Body parameter

 Paramete         Data             Require          Description
 r                Type             d
 deviceIds        String[]         Yes              Device ID list, limited to 200.

HTTP status code

 Code                Description
 200                 Operation successful
 400                 Client parameter exception
 401                 Authentication failed
                                                                                        33 / 164
Open API for Yealink Management Cloud Service V4X



 500                 Server exception

Response parameters

 Parameter              Data             Description
                        Type
 total                  Integer          Delete total count
 successCount           Integer          Total number of successful deletions.
 failureCount           Integer          The total number of failures.
 errors                 OpError[]        Error message.

OpError object

 Parameter                     Data Type                  Description
 field                         String                     Error field
 msg                           String                     Error message.

Example Request

  httpPOST /v2/dm/deviceGroups/00884cef841e48f4acd213c084e65f67/addDevices
  HTTP/1.1
  Host: api.ymcs.yealink.com
  Content-Type: application/json

  {
  "deviceIds":
  ["0006572538f74e8683716cf961caa95b","00099642675e4d4bb5e91fd9ae5ce585"]

  }


Example Response

  httpHTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8

  {
  "total": 2,
  "successCount":1,
  "failureCount":1,
  "errors":[{
                                                                                 34 / 164
Open API for Yealink Management Cloud Service V4X


  "field":"00099642675e4d4bb5e91fd9ae5ce585",
  "msg":"The resource does not exist or has been deleted"
  }]
  }


2.2.6 Remove devices from the group
Request Method
POST
Request URL
/v2/dm/deviceGroups/{deviceGroupId}/delDevices
PATH parameter

 parameter                        Data Type           Required       Description
 deviceGroupId                    String              Yes            Group ID

Body parameter

 Paramet         Data             Require       Description
 er              Type             d
 deviceIds       String[]         Yes           Device ID list, maximum length 200

HTTP status code

 Code                Description
 200                 Operation successful
 400                 Client parameter exception
 401                 Authentication failed
 500                 Server exception

Response parameters

 Parameter              Data             Description
                        Type
 total                  Integer          Delete total count
 successCount           Integer          Total number of successful deletions.
 failureCount           Integer          The total number of failures.

                                                                                     35 / 164
Open API for Yealink Management Cloud Service V4X



 errors                 OpError[]        Error message.

OpError object

 Parameter                     Data Type                  Description
 field                         String                     Error field
 msg                           String                     Error message.

Example Request

  httpPOST /v2/dm/deviceGroups/00884cef841e48f4acd213c084e65f67/delDevices
  HTTP/1.1
  Host: api.ymcs.yealink.com
  Content-Type: application/json

  {
  "deviceIds":
  ["0006572538f74e8683716cf961caa95b","00099642675e4d4bb5e91fd9ae5ce585"]

  }


Example Response

  httpHTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8

  {
  "total": 2,
  "successCount":1,
  "failureCount":1,
  "errors":[{
  "field":"00099642675e4d4bb5e91fd9ae5ce585",
  "msg":"The resource does not exist or has been deleted"
  }]
  }


2.2.7 Query Device List within Group
Request Method
POST
Request URL
                                                                             36 / 164
Open API for Yealink Management Cloud Service V4X



/v2/dm/deviceGroups/{deviceGroupId}/listDevices
PATH parameter

 parameter                        Data Type         Required      Description
 deviceGroupId                    String            Yes           Group ID

Body parameter

 Pa     Da      Re    Description
 ra     ta      qu
 me     Ty      ir
 te     p       e
 r      e       d
 sk     Lo      N     Number of skipped records, default is 0
 ip     ng      o
 li     Lo      N     Maximum number of records to retrieve, default is 10,
 mi     ng      o     maximum is 500.
 t
 au     Bo      N     Whether to respond with the total count, it is recommended
 to     ol      o     to set it to true when querying the first page, and pass false
 Co     ea            for subsequent page turns.
 un     n
 t
 fil    Fil     N     search parameters
 te     te      o
 r      r

Filter object definition

 Para         Dat    Re     Description
 mete         a      qu
 r            Ty     ire
              pe     d
 mac          Str    No     Device MAC fuzzy search keyword, maximum length 17,
              ing           supports with : or -, such as 00:15:65:bb:b1:a9
 mode         Str    No     Model ID
 lId          ing
                                                                                 37 / 164
Open API for Yealink Management Cloud Service V4X



 devic      Int     No      Device status, 1: online, 0: offline, -1: not reported
 eStat      ege
 us         r

HTTP status code

 Code                Description
 200                 Operation successful
 400                 Client parameter exception
 401                 Authentication failed
 500                 Server exception

Response parameters

 Parameter            Data Type            Description
 skip                 Long                 offset
 limit                Long                 The maximum returned number.
 total                Long                 Total quantity
 data                 Device[]             Device information array

Device object definition

 Paramete         Data       Description
 r                Type
 id               Strin      device id
                  g
 mac              Strin      Device MAC
                  g
 sn               Strin      Device SN
                  g
 name             Strin      Device Name
                  g
 modelId          Strin      Model ID
                  g
 siteId           Strin      Site ID
                  g
                                                                                     38 / 164
Open API for Yealink Management Cloud Service V4X



 programV         Strin      Device firmware version number
 ersion           g
 deviceSta        Strin      Device status, online: online, offline: offline, pending:
 tus              g          not reported


  httpPOST /v2/dm/deviceGroups/00884cef841e48f4acd213c084e65f67/listDevices
  HTTP/1.1
  Host: api.ymcs.yealink.com
  Content-Type: application/json

  {
  "skip": 0,
  "limit": 10,
  "autoCount": true
  }


Example Response

  httpHTTP/1.1 200
  Content-Type: application/json;charset=UTF-8

  {
  "skip": 0,
  "limit": 10,
  "total": 1,
  "data":[{
  "id": "8d07a56207074d26b61026099625b9e2",
  "mac":"001565bbb1a9",
  "sn":"1106312113402006",
  "name":"my t54s",
  "modelId":"61e659e4d78d42ebada88ef1eb751b64",
  "siteId":"a624453e1cbb44ecb9bb6ee31731a856",
  "programVersion":"70.83.0.68",
  "deviceStatus":"online"
  }]
  }


2.3 Device Control
2.3.1 Device Restart
Request Method
                                                                                     39 / 164
Open API for Yealink Management Cloud Service V4X



POST
Request URL
/v2/dm/device/reboot
Body parameter

 Paramet         Data          Requi        Description
 er              Type          red
 deviceIds       String[]      Yes          Device ID list, maximum length 200
 deviceTy        Integer       Yes          Device Type 1: Phone Device 3: Room
 pe                                         Device

HTTP status code

 Code                Description
 200                 Operation successful
 400                 Client parameter exception
 401                 Authentication failed
 500                 Server exception

Response parameters

 Parameter             Data            Description
                       Type
 total                 Integer         Total number of factory restored devices
 successCoun           Integer         Number of successful factory restored
 t
 failureCount          Integer         Number of failed factory restored
 errors                OpError[]       Error message.

OpError object

 Parameter                     Data Type                  Description
 field                         String                     Error field
 msg                           String                     Error message.

Example Request

                                                                                  40 / 164
