Request Structure

The request URL consists of several parameters, such as base URL, API version, token, and API-specific parameters. This topic describes the request structure, including communication protocol, request methods, and the URL format.

Structure example

Below is a request example of Log in a Queue.

POST /api/v2.0.0/queue/add_dynamicagent?token=1e3b3ebb6a974cb42ed31de5413df52d 
Content-Type:application/json; charset=utf-8
Host: 192.168.5.150

{
	"queuenumber": "6700",
	"extnumber": "1000",
	"password": "6700123"
}
  • POST indicates the request method.
  • /api/v2.0.0 is the API path which indicates the API version.
  • queue/add_dynamicagent indicates the target API Log in a Queue.
  • token=1e3b3ebb6a974cb42ed31de5413df52d indicates the token used for authentication.
  • Content-Type:application/json; charset=utf-8 indicates the format of request content.
  • Host indicates the IP address of Yeastar S-Series VoIP PBX.
  • queuenumber, extnumber, password are the request parameters of Log in a Queue.

Communication protocols

Yeastar S-Series VoIP PBX API supports HTTP protocol or HTTPS protocol for communication. All API requests use POST method. For security reasons, we recommend that you use HTTPS protocol to send API requests.

Request URL format

The request URL format is as follows:

Note: No token is needed in the request URL of Get API token.
{base_url}/{api_path}/{endpoint}?token={token}
{base_url}

Set the API base URL according to the web access settings on your PBX.

  • If the web access protocol of PBX is HTTPS, use the following base URL:
    https://{pbx_ip}:{https_port}
  • If the web access protocol of PBX is HTTP, use the following base URL:
    http://{pbx_ip}:{http_port}
{api_path}
The format of API path is api/{version}; the {version} indicates the API version.
All URLs referenced in the documentation use API version v2.0.0, and the API path is api/v2.0.0.
{endpoint}

Endpoint, also called path, indicates the specific address of API request.

Refer to API Interfaces & Events Overview for all available Endpoints on Yeastar S-Series VoIP PBX.

{token}

Token is used to authenticate API requests. The application server should Get API token before calling APIs. Each subsequent request requires the token for authentication.

For detailed API authentication, refer to API Authentication Methods.