# Open API for Yealink Management Cloud Service V4X.pdf - Pages 1-20

**Source:** Open API for Yealink Management Cloud Service V4X.pdf
**Pages:** 1-20 of 164
**Chunk:** 1

---

Open API for Yealink Management Cloud Service V4X




Open API for Yealink Management
Cloud Service V4X
1. YMCS APIs
1.1 Introduction
YMCS Open API provides third-party developers with a portal to securely use
device management services. Through YMCS APIs, developers can use YMCS's
device management, account management, configuration management and
other functions.
YMCS API is a REST-like API based on HTTP. The REST-like style indicates that the
resource is tagged using a URI and allows access to the API via the HTTP
protocol. The API relies on HTTP semantics and methods.
In order to ensure the security of using the YMCS API, the transport protocol is
unified using HTTPS and all requests need to be authenticated. If the YMCS API
is used without carrying the correct identity credentials information, the request
will be rejected outright. More information about YMCS authentication will be
detailed in 1.2.2 Authentication.
The YMCS platform limits the frequency of API calls to ensure system stability.
Most endpoints are rate-limited to 50 requests per second. This rate limit is at
the enterprise level, for each enterprise that supports the YMCS API, we allow 50
requests per second. More information on rate limiting is detailed in Invoking Rate
Limiting.

1.2 Use YMCS APIs
YMCS APIs allow developers to access and manipulate resources under YMCS,
including but not limited to device management, account management,
configuration management, and other operations. This chapter will describe
how to correctly call the YMCS API.
YMCS API
                                                                              1 / 164
Open API for Yealink Management Cloud Service V4X


  Version: 1.0.0
  Host:
    If your enterprise is in the EU region: eu-api.ymcs.yealink.com
    If your enterprise is in the US region: us-api.ymcs.yealink.com
    If your enterprise is in the AU region: au-api.ymcs.yealink.com
  Protocols: HTTPS
  Accepts: application/json
  Responds With: application/json

Authentication
Every HTTP request made to the YMCS API must go through authentication. This
operation is to ensure whether the client accessing the service is a registered
user of the system. During the process of authentication, OAuth2.0 protocol will
be used.
Before calling the API, you need to obtain the Client ID and Client Secret from
the YMCS platform to apply for an access token. An enterprise can only apply for
one set of Client ID and Client Secret.
Process Description
The process for a user to request access tokens and initiate requests is as
follows:




                                                                              2 / 164
Open API for Yealink Management Cloud Service V4X




1. The third-party application server initiates and sends a request, carrying the Client ID and Client Secret, to the
   YMCS API server to access a token.
2. The API server verifies whether the Client ID and Client Secret information is correct.
3. Yealink API server returns access token after successful verification.
4. The third-party application server initiates a business request and carries an access token.
5. Yealink API server checks for the existence of an access token, and then verifies the validity of the access
   token.
6. Yealink API server forwards the request to the Yealink business server.
7. Yealink business server will return the processed result to the Yealink API server.
8. The API server will pass the response result to the third-party application server.


   If the access token is invalid, you will need to provide the corresponding code
   to retrieve the token from the server again.

Apply for access token
Request Method
POST
Request URL
/v2/token
Request parameters

                                                                                                              3 / 164
Open API for Yealink Management Cloud Service V4X



 Param        Parame        Data       Requ         Description
 eter         ter           Type       ired
              Type
 Author       Header        String     Yes          Basic
 ization                                            base64Encode(client_id:client_secret),
                                                    connect Client ID and Client Secret with
                                                    a colon, and then perform Base64
                                                    encoding.
 times        Header        String     Yes          Timestamp, the number of
 tamp                                               milliseconds from January 1, 1970,
                                                    00:00:00 to now.
 nonce        Header        String     Yes          Random number, maximum length 32
                                                    bits
 grant_       Body          String     Yes          client_credentials
 type

HTTP status code

 Code           Description
 200            Operation successful, see response parameters.
 400            Client parameter transmission exception, see exception response
                parameters for details.
 401            Authentication failed, see exception response parameters.
 500            Server exception, see exception response parameters for details.

Response parameters

 Parameter             Data Type                Description
 access_token          String                   access token
 token_type            String                   bearer
 expires_in            Long                     Access token validity period, in seconds.

Exception response parameters

 Par       Data        Description
 ame       Type
 ter
                                                                                         4 / 164
Open API for Yealink Management Cloud Service V4X



 erro      String      Provide error codes according to the definition of the OAuth2
 r                     protocol. Error coded can be used to categorize and handle
                       errors.
 cod       String      Server-defined error code, used for quick problem
 e                     localization.
 requ      String      Request ID generated by the server to track the execution
 estI                  status of the request on the server side. It can help
 d                     developers quickly identify issues.
 mes       String      Clear and concise error Description that can be understood
 sage                  by end users.

Example Request

  httpPOST /v2/token HTTP/1.1
  Content-Type: application/json
  Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

  {
  "grant_type": "client_credentials"
  }


Example of response parameters

  httpHTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache

  {
  "access_token": "[JWT TOKEN]",
  "token_type": "bearer",
  "expires_in": 86400
  }


Exception response parameters

  httpHTTP/1.1 400 Bad Request
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store

                                                                                   5 / 164
Open API for Yealink Management Cloud Service V4X


  Pragma: no-cache

  {
  "error": "invalid_request",
  "code": "70011",
  "requestId": "255d1aef",
  "message": "The provided value for the input parameter 'grant_type' is not valid."
  }


Initiate business request
All API requests must be made via HTTPS. The base URL for requests is https://
api.ymcs.yealink.com/v2/. The complete URL varies depending on the resource of

the operation.
Each time you request the API, you must provide 3 HTTP Request Headers, as
follows:

 Name             Data Type         Description
 Authoriza        String            Authentication information. The format is: Bearer
 tion                               [ACCESS TOKEN]

 timestam         String            Timestamp, the number of milliseconds from
 p                                  January 1, 1970, 00:00:00 to now.
 nonce            String            Random number, maximum length 32 bits

HTTP Request Header Example

  httpAuthorization: Bearer [ACCESS TOKEN]
  timestamp: 1568693976264
  nonce: 097e0ac619ba41f68f16f1955787feb9


1.3 Error Definitions
Yealink API uses HTTP status codes to reflect the success or failure of request
operations. 2XX status codes indicate successful operations, while 4XX or 5XX
status codes indicate operation errors. If an erroneous status code is received,
the error code and error message in the response body can be used to
understand the reason for the error.

                                                                                       6 / 164
Open API for Yealink Management Cloud Service V4X



 Status code              Description                   Scenario example
 2XX                      Operation successful
 400                      Request data error            Invalid or incomplete
                                                        request data.
 401Authenticati          Authentication error          The request did not carry
 on error                                               an access token.
 403                      Access to certain resources   Authentication failed
                          is not allowed
 404                      No data matching the          No data found.
                          request
 429                      Request rate exceeds          Request too frequent
                          frequency limit
 500                      Server Error                  Internal server error

Error object definition
Error object

 Na       Data      Description
 me       Typ
          e
 cod      Stri      Error codes defined by the server, used for quick problem
 e        ng        localization.
 req      Stri      Request ID generated by the server, used for tracking the
 uest     ng        execution status of requests on the server. It helps developers
 Id                 quickly locate issues.
 mes      Stri      A simple and clear error Description that can be understood by
 sag      ng        the end user.
 e
 deta     Error     List of details that caused the error, may be empty
 ils      Detai
          l[]

ErrorDetail object

 Name            Data          Description
                 Type
                                                                                 7 / 164
Open API for Yealink Management Cloud Service V4X



 field         String          Error in the request parameter name
 messag        String          A simple and clear error Description that can be
 e                             understood by the end user.

Error Response Example

  json{
  "code": "{errorCode}",
  "requestId": "{requestId}",
  "message": "Validation Failed",
  "details": [
  {
  "field": "email",
  "message": "Invalid field"
  },
  {
  "field": "type",
  "message": "Invalid field"
  }
  ]
  }




 Opera Description                                             Description
 tional
  code
 90020       Operation successful                              Operate Successfully
 0
 90040       Incorrect request parameters                      Request parameters
 0                                                             are incorrect
 90040       The user has not logged in or the login has       User is not logged in
 1           expired, please log in again                      or the account has
                                                               expired, please log in
                                                               again
 90040       The request has been forbidden.                   This request is
 3                                                             forbidden
 90040       The requested resource cannot be found.           Requested resource is
                                                                                   8 / 164
Open API for Yealink Management Cloud Service V4X



 4                                                           not found
 90040       Request timed out, please try again later.      Time out, please try
 8                                                           again
 90040       Conflict request.                               Request conflict
 9
 90041       Concurrent editing error.                       Concurrent editing
 2                                                           error
 90042       Too many requests.                              Too Many Requests
 9
 90044       Session expired.                                Login Time-out
 0
 90050       The server is busy, please try again later.     The server is busy,
 0                                                           please try again later
 90050       This operation is not supported.                Not Implemented
 1
 90050       When a server acting as a gateway or proxy      Bad Gateway
 2           attempts to process a request, it receives an
             invalid response from the upstream server.
 90050       Service Unavailable.                            Service Unavailable
 3
 90050       The upstream server is not responding.          Gateway Timeout
 4
 90051       Internal server error                           Server Internal Error
 1
 90059       Unknown error                                   unknown mistake
 9
 90040       Parameters cannot be null                       Cannot be null
 0
 90040       Parameters cannot be null                       Cannot be empty
 0
 90040       The parameter length is incorrect.              Incorrect length
 0
 90040       ID cannot be empty.                             ID cannot be empty

                                                                                  9 / 164
Open API for Yealink Management Cloud Service V4X



 0
 90040       Resource does not exist                      The resource does not
 0                                                        exist or has been
                                                          deleted
 80000       Mac is not legal.                            Invalid MAC
 1
 80000       Invalid SN.                                  SN is invalid
 2
 80000       Resource already exists.                     Resource already
 3                                                        exists
 80000       The device has been added by another         MAC has been added
 4           company.                                     by another
                                                          enterprise/
                                                          organization
 80000       Device type illegal                          Device Type is invalid
 5
 80000       The number of devices added in a batch       The number of added
 6           exceeds the limit                            devices exceeds the
                                                          limit
 80000       Invalid parameters.                          Incorrect parameter
 7                                                        format
 80000       Data exceeds limit.                          Data exceeds limit
 8
 80013       Account already exists                       Account already exists
 0
 80020       The authentication username and              Username and
 0           password must appear in pairs.               password must
                                                          appear in pairs

1.4 Invoke Rate Limiting
In order to maintain the reliability of the YMCS API platform, our API has the
following rate limits.
The rate limit for the normal API is 50 requests/second unless otherwise noted.
Please control the frequency of your application calls and do not exceed the
                                                                               10 / 164
Open API for Yealink Management Cloud Service V4X



access rate limit or you will receive a 429 status response.
Invokers of the YMCS API shall retry Error 429 using the exponential backoff
algorithm and with a minimum delay of 30 seconds.

2. Device Management
2.1 Device Basic Information Management
2.1.1 Add Devices
Request Method
POST
Request URL
/v2/dm/devices
Body parameter

 Paramet        Data            Required            Description
 er             Type
 mac            String          Yes                 Device MAC, minimum length 12,
                                                    maximum length 17 characters
 sn             String          Yes                 SN code, maximum length 128
 deviceT        Integer         Yes                 Device Type 1: Phone Device 3: Room
 ype                                                Device
 modelId        String          Yes                 Model ID
 name           String          No                  Device name, maximum length 128
 siteId         String          No                  Site ID

HTTP status code

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

Response parameters


                                                                                      11 / 164
Open API for Yealink Management Cloud Service V4X



 Parameter                Data Type                 Description
 id                       String                    The device ID.
 mac                      String                    The device MAC address.
 sn                       String                    The group ID.
 name                     String                    The device name.
 modelId                  String                    The device model ID.
 siteId                   String                    The site ID.
 programVersion           String                    The version number of the device
                                                    firmware.

Example Request

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

  {
  "mac":"001565bbb1a9",
  "sn":"1106312113402006",
  "name":"my t54s",
  "deviceType":1

  }


Example Response

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

  {
  "id": "8d07a56207074d26b61026099625b9e2",
  "mac":"001565bbb1a9",
  "sn":"1106312113402006",
  "name":"my t54s",
  "modelId":"61e659e4d78d42ebada88ef1eb751b64",
  "siteId":"a624453e1cbb44ecb9bb6ee31731a856",
  "programVersion":"70.83.0.68"
  }


                                                                                  12 / 164
Open API for Yealink Management Cloud Service V4X


2.1.2 Add Device in Batches
Note: You can add up to 100 devices at a time.
Request Method
POST
Request URL
/v2/dm/addDevices
Body parameter

 Paramete          Data Type          Required       Description
 r
 mac               String             Yes            Device MAC, minimum length 12,
                                                     maximum length 17
 sn                String             Yes            SN code, maximum length 128
 deviceTyp         Integer            Yes            Device Type 1: Phone Device 3:
 e                                                   Room Device
 modelId           String             Yes            Model ID
 name              String             No             Device name, maximum length
                                                     128
 siteId            String             No             Site ID

HTTP status code

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

Response parameters

 Parameter            Data Type        Description
 total                Integer          The total number of batch additions.
 successCoun          Integer          The total number of successful additions.
 t

                                                                                   13 / 164
Open API for Yealink Management Cloud Service V4X



 failureCount         Integer          The total number of failures.
 errors               AddError[]       Error message.

AddError object

 parameter               Data Type              Description
 mac                     String                 The device MAC address.
 sn                      String                 The device SN address.
 errorInfo               String                 Error message.

Example Request

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

  [{
  "mac":"3a1565bbb1a9",
  "sn":"1106312113402006",
  "name":"my t54s",
  "modelId":"61e659e4d78d42ebada88ef1eb751b64",
  "deviceType":1

  }]


Example Response

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

  {
  "total": 1,
  "successCount":0,
  "failureCount":1,
  "errors":[{
  "mac":"3a1565bbb1a9",
  "sn":"1106312113402006",
  "errorInfo":"device.mac.invalid"
  }]
  }


                                                                          14 / 164
Open API for Yealink Management Cloud Service V4X


2.1.3 Add device without SN
Note: You can add up to 100 devices at a time.
Request Method
POST
Request URL
/v2/dm/addDevicesByMac
Body parameter

 Param        ParameterT           Data         Requi   Description
 eter         ype                  Type         red
 mac          Body                 String       Yes     Device MAC, minimum length
                                                        12, maximum length 17
 device       Body                 Integer      Yes     Device Type 1: Phone Device 3:
 Type                                                   Room Device
 model        Body                 String       Yes     Model ID
 Id
 name         Body                 String       No      Device name, maximum length
                                                        128
 siteId       Body                 String       No      Site ID

HTTP status code

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

Response parameters

 Parameter            Data Type        Description
 total                Integer          The total number of batch additions.
 successCoun          Integer          The total number of successful additions.
 t
 failureCount         Integer          The total number of failures.
                                                                                   15 / 164
Open API for Yealink Management Cloud Service V4X



 errors               AddError[]       Error message.

 Parameter               Data Type              Description
 mac                     String                 The device MAC address.
 sn                      String                 The device SN address.
 errorInfo               String                 Error message.

Example Request

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

  [{
  "mac":"3a1565bbb1a9",
  "name":"my t54s",
  "modelId":"61e659e4d78d42ebada88ef1eb751b64",
  "deviceType":1

  }]


Example Response

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

  {
  "total": 1,
  "successCount":0,
  "failureCount":1,
  "errors":[{
  "mac":"3a1565bbb1a9",
  "sn":"1106312113402006",
  "errorInfo":"device.mac.invalid"
  }]
  }


2.1.4 Delete Device
Request Method

                                                                          16 / 164
Open API for Yealink Management Cloud Service V4X



DELETE
Request URL
/v2/dm/devices/{deviceId}
PATH parameter

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

HTTP status code

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

Example Request

  httpDELETE /v2/dm/devices/e33b8f25247e45de84dd4c74503b241a HTTP/1.1
  Host: api.ymcs.yealink.com


Example Response

  httpHTTP/1.1 204


2.1.5 Delete Devices in Batches
Request Method
POST
Request URL
/v2/dm/delDevices
Body parameter

 Parame Data             Req       Description
 ter    Type             uire
                         d

                                                                            17 / 164
Open API for Yealink Management Cloud Service V4X



 device        Integ     Yes       Device Type 1: Phone Device 3: Room Device
 Type          er
 deviceI       Strin     No        Indicates the type of device identifier, default id,
 dType         g                   optional mac, id
 deviceI       Strin     Yes       Device identifier, maximum length 200
 ds            g[]

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.
 errors                 OpError[]        Error message.

OpError object

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

Example Request

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

  {

                                                                                      18 / 164
Open API for Yealink Management Cloud Service V4X


  "deviceType":1,
  "deviceIds":["001565bbb1a9","001567"],
  "deviceIdType":"mac"
  }


Example Response

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

  {
  "total": 2,
  "successCount":1,
  "failureCount":1,
  "errors":[{
  "field":"001567",
  "msg":"Invalid MAC"
  }]
  }


2.1.6 Device List
Request Method
POST
Request URL
/v2/dm/listDevices
Body parameter

 Par Data            Req Description
 ame Type            uir
 ter                 ed
 ski      Long       No      Number of skipped records, default is 0
 p
 limi     Long       No      Maximum number of records to retrieve, default is 10,
 t                           maximum is 100.
 aut      Bool       No      Whether to respond with the total count, it is
 oCo      ean                recommended to set it to true when querying the first
 unt                         page, and pass false for subsequent page turns.

                                                                                19 / 164
Open API for Yealink Management Cloud Service V4X



 filte    Filter     No      search parameters
 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
 model       Str     No      Model ID
 Id          ing
 devic       Int     No      Device status, 1: online, 0: offline, -1: not reported
 eStat       ege
 us          r
 accou       Int     No      Account status, 1: Registered 2: dnd 3: Unregistered
 ntSta       ege
 tus         r
 devic       Int     No      Device type status, 1: Phone Device 3: Room Device, if
 eType       ege             not filled in, it means all.
             r
 siteId      Str     No      Site ID
             ing

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                 The offset value.
                                                                                      20 / 164
