When using the Udesk Open API (v2), the following rules must be followed:

  • The default frequency limit for APIs is 60 times/minute, so any API can be called up to 60 times in 1 minute;
  • All APIs are designed for server-side calls, please do not call them on the client side (web front-end pages, mobile applications, etc.), otherwise there may be a risk of authentication token leakage.

Call Format

HTTP Method

The Udesk Open API (v2) may use the following HTTP methods:

  • GET: Used to obtain data interface
  • POST: Used to create interface
  • PUT: Used to modify interface
  • DELETE: Used to delete interface

We will indicate the HTTP method used in each interface document. Please refer to the specific interface document when calling the interface.

Call Address

The call address of the Udesk development interface conforms to the following format:


The meanings of the parts enclosed in brackets are as follows:

subdomainThe subdomain you use to access the Udesk customer service system.
interface_relative_addressThe relative URL of the specific API you are calling, which will be indicated in each API.
URL_parametersQuery String parameters required by the interface.
administrator_emailYour super administrator email.
timestampThe timestamp when the request was initiated, in Unix Time format, i.e. the number of seconds from "1970-01-01 00:00:00" to now.
signatureThe signature for identity authentication. Unless otherwise specified, it needs to be carried with each API call. See Authentication Method for the calculation method.
unique_identifier_of_requestCan only be used once within 15 minutes.
signature_algorithm_versionThe value is fixed as v2.

Each interface document will give a call method similar to the following: GET /customers It contains the HTTP method and the relative address of the interface. Other parts need to be replaced according to the specific situation.


There may be three types of parameters in the interface document:

  • In the URL: Parameters embedded in the call address, such as :id in /customers/:id;
  • Query String: Parameters in the Query String part of the call address, such as page in /customers?page=2;
  • Request Body: The content in the request body. When calling creation or modification interfaces, you need to convert the request data into UTF-8 text in JSON format and pass the encoded string as a Request Body parameter to the corresponding interface. Also set the Content-Type field in the request header to application/json.

Return Results

The return data of the Udesk Open API (v2) is also a UTF-8 string encoded in JSON format.

Code Error Code and Description

See Code Error Code Description

Authentication Method

Rule Description

All interface calls need to carry the signature parameter sign. Only when the sign value is legal will the request be accepted. The calculation method of sign is as follows:


Note: If SHA256 authentication fails, please use SHA1 Where:

  • email is the email address of the super administrator;
  • open_api_token is the API authentication token, which needs to be obtained by calling Get Authentication Token Interface;
  • timestamp is Unix time, i.e. the number of seconds from "1970-01-01 00:00:00" to now;
  • nonce is a unique string provided by the caller, which can only be used once within 15 minutes;
  • sign_version is the signature algorithm version, and the value is fixed as v2.


Suppose you want to call the following interface:


The data required for authentication is as follows:

Administrator emailadmin@udesk.cn
API Token233df89e-b4a2-42e0-89af-f295b1078686

Calculate sign

sha256("admin@udesk.cn&233df89e-b4a2-42e0-89af-f295b1078686&1494474404&2d931510-d99f-494a-8c67-87feb05e1594&v2") #=> 6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52

Note: If sha256 authentication fails, please use sha1 The final request URL:


Authentication Failure Return Data

Attribute NameValueDescriptionRemarks
code2059Open API signature is incorrectAuthentication failed (authentication parameter error)

Common Data

Paging Information

When obtaining a list and other interfaces, the returned data usually carries paging information (meta), which is as follows:

Attribute NameTypeDescription
current_pageIntegerCurrent page number
total_pagesIntegerTotal number of pages
total_countIntegerTotal amount of data

Code Error Code Description

Error CodeMessage InformationException: Message InformationDescription
2002Invalid subdomainNoneDomain name input error
2005Parameter errorNonePassword input error
2015Non-administrators cannot operateNoneThe identity used for authentication is not an administrator
The resource was not foundNoneAccount input error or no such account
2058Your company is not a professional versionNoneThe company has not paid
2059Open API signature is incorrectNoneAuthentication parameter error
20621The timestamp format is incorrectSame as messageRequired parameter {timestamp} is not filled in or the format is incorrect
20622The timestamp error cannot exceed 5 minutesSame as messageThe difference between parameter {timestamp} and the current time exceeds 5 minutes
20623The request is only valid once, and the nonce value cannot be repeated within 15 minutesSame as messageThe authentication parameter {nonce} has been used within 15 minutes
20624Open API nonce is emptySame as messageThe authentication parameter {nonce} is not filled in or is empty
2000Unknown errorparam is missing or the value is empty: notice_url notice_url parameter is emptynotice_url parameter cannot be empty