Login

Enable API access on the Yeastar S-Series VoIP PBX, then access the PBX by the API username and the encrypted MD5 API password.

Note:
  • You need to encrypt the API password with MD5 first, and use the MD5 password to log in.

    The MD5 password should be in the format of 32 lowercase letters.

  • If you log in failed consecutively for 5 times, you need to try after 10 minutes.

Endpoint

POST /api/v1.10/login

Request Parameters

Name Importance Type Description
username Required String The PBX API's username.
password Required String The PBX API's password.

Encrypt the password with MD5, then fill in the encrypted 32 lowercase letters.

port Required String The API port number that is set on 3rd-party application. The PBX will send API reports to the 3rd-party application via this port.

Port range: 0 ~ 65536.

version Optional String The version of API reports format.
Note:
  • If you don't add version in the request, the PBX will send the API reports in the default format.
  • We updated the report format to well-formed JSON format. Adding "version":"1.0.2" in the request will fix the problem that the API reports are not in well-formed JSON format.
url Optional String URL of the application server. This URL is used to specify the sending path of event report to the application server.
Note: If the parameter is not specified, the event report will be sent to the IP address of the application server.
urltag Optional String Specify the URL type:
  • 0: The URL is a relative URL.

    For example, the IP address of the application server is 110.22.2.3, port is 8260, url is "report"; PBX will send the API reports to 110.22.2.3:8260/report .

  • 1: The URL is an absolute URL.

    For example, the IP address of the application server is 110.22.2.3, url is "110.22.2.3:8260/report"; PBX will send the API reports to "110.22.2.3:8260/report".

    Note: Using an absolute URL will ensure the API reports to be sent successfully in an complicated network environment.

Response Parameters

Name Type Description
token String Token for interface invocation.
Note:
  • All API requests should contain an API token.

    The API token is generated when the 3rd-party application server logs in the PBX API successfully.

  • The API token is valid in 30 minutes.

    Within the validity time of the token, if there is no event interaction between the API and the application server ( for example, the application server sends API request to the PBX, or PBX API sends event report to the application server), the token will be erased by the PBX.

    The application server can prolong the validity time of the token by sending a Heartbeat packet to the PBX via the Heartbeat packet interface. Every time a packet is sent, the token validity time will be prolonged for 30 minutes.

Examples

Request Example
POST /api/v1.1.0/login HTTP/1.1
Content-Type:application/json; charset=utf-8
Host: 192.168.5.150
{
    "username": "api",
    "password": "2d7257a528679d01a19c70e3fa773620",
    "port": "8260",
    "version": "1.0.2",
    "url": "110.22.2.3:8260/report",
    "urltag": "1"
}
Response Example

Login success.

HTTP/1.1 200 OK
Access-control-allow-origin: *
Access-control-allow-methods: GET, POST, OPTIONS, PUT, DELETE
{
    "status": "Success",
    "token": "48a7d7481a5355aa4fb5dc285edeb40e"
}
Login failure.
HTTP/1.1 200 OK
Access-control-allow-origin: *
Access-control-allow-methods: GET, POST, OPTIONS, PUT, DELETE
{
      "status": "Failed", 
      "errno": "30003"
}