Mike Swanson
6942827391
Author: Mike Swanson Machine: Mikes-MacBook-Air.local Timestamp: 2026-07-09 14:52:07
28 KiB
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
- 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
-
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.
-
The API server verifies whether the Client ID and Client Secret information is correct.
-
Yealink API server returns access token after successful verification.
-
The third-party application server initiates a business request and carries an access token.
-
Yealink API server checks for the existence of an access token, and then verifies the validity of the access token.
-
Yealink API server forwards the request to the Yealink business server.
-
Yealink business server will return the processed result to the Yealink API server.
-
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.
- 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