General Principles

HTTP Request Methods

The CASE service should adhere as closely as possible to standard HTTP and REST principles.

Request MethodUsage
GETRetrieve a resource
POSTCreate a new resource or query an existing one
PUTUpdate an existing resource
DELETEDelete an existing resource


CASE service responses that require pagination will conform to the following message format:

pagingObjecttruePagination object
paging.pageNumIntegertruePage number
paging.pageSizeIntegertruePage size
paging.totalLongtrueTotal number of items

HTTP Status Codes

The CASE service should adhere as closely as possible to standard HTTP and REST principles.

Status CodeUsage
200 OKStandard response for successful HTTP requests. The actual response will depend on the request method. For GET requests, the response will contain an entity corresponding to the requested resource. For POST requests, the response will contain a description of the entity or the result of the action.
201 CreatedThe request has been fulfilled, resulting in the creation of a new resource.
204 No ContentThe server successfully processed the request but is not returning any content.
400 Bad RequestThe server cannot or will not process the request due to client error (e.g., incorrect syntax, invalid request message framing, deceptive request routing).
401 UnauthorizedUnauthorized.
404 Not FoundThe requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
500 Internal Server ErrorA generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

Invocation Address


https://km.udesk.cn/api/v1/{relative address}?{URL params}&email={administrator email}&timestamp={timestamp}&sign={signature}

Where parts in curly brackets mean:

relative address: Interface relative addressThe relative URL of the API
URL params: URL parametersParameters required for requesting the interface
administrator email: Administrator emailThe email address of the super administrator
timestamp: TimestampThe timestamp when the request is initiated, in seconds since '1970-01-01 00:00:00'. Unless otherwise specified, the default expiration time is five minutes.
signature: SignatureAuthentication signature. Unless otherwise specified, this parameter is required for each API request. Refer to the detailed generation algorithm in the "Authentication Method" section.

Parameters Three types of parameters:

Path parametersPart of the request URL Path, such as :id in /leads/:id
Query parametersParameters when requesting the interface, such as page=10 in /leads?page=10
Request fieldsRequest body (Request Body)

Return UTF-8 encoded JSON string

Authentication Method




  • email: Administrator email address
  • api_token: Authentication private key, available in the km system at Top right corner gear (Admin) - System settings - Key
  • timestamp: Timestamp, in seconds since '1970-01-01 00:00:00'



Data required for authentication:


Calculate the signature:

sha1("email@udesk.cn&221b368d7f5f597867f525971f28ff75&1496631984") -> a32be53bb42314850715f8b9ab92542f5ed54c5e

Request URL: