Request Structure

The request URL consists of several parameters, such as host URL, API version, access token, API endpoint and required parameters. This topic describes the request structure, including request methods and request URL format.

Request example

Important: You MUST include a User-Agent header with every request that you submit to the Yeastar P-Series PBX System API, so that the PBX can identify your application and respond to the request. For example,

User-Agent:
                OpenAPI

Below is a request example of Edit an Extension.

POST /openapi/v1.0/extension/update?access_token=5SwyByhbSfsNlpI1v4GtHxEDmKsZwzjQ HTTP/1.1 
Host: 192.168.5.150:8088
Content-Type: application/json
User-Agent: OpenAPI
{
    "id": 60,
    "presence_status":"off_work"
}

POST indicates the request method.
openapi/v1.0 is the API path that indicates the API version.
extension/update indicates the target API endpoint of Edit an Extension.
access_token=5SwyByhbSfsNlpI1v4GtHxEDmKsZwzjQ is the access token used for authentication.
HTTP/1.1 is the Hypertext Transfer Protocol.
Host indicates the IP address or the domain name of Yeastar P-Series PBX System.
Content-Type:application/json indicates the format of request content.
id and presence_status are the request parameters of Edit an Extension.

Request methods

Yeastar P-Series PBX System API supports the following request methods:

GET - to query information or execute delete operations.
POST - to add an object or execute specific operations.

Request URL format

The request URL format is as follows:

{base_url}/{api_path}/{endpoint}?access_token={access_token}

Note: No access token is needed in the request URL of Get Access Token and Refresh Access Token.

{base_url}

All URLs referenced in the documentation have the following base URL:

https://{pbx_ip}:{https_port}

You can set the API base URL according to the web access settings on your PBX.

If the web access protocol of PBX is HTTP, use the following base URL:
```
http://{pbx_ip}:{http_port}
```
If the web access protocol of PBX is HTTPS, use the following base URL:
```
https://{pbx_ip}:{https_port}
```
If you use the Yeastar FQDN for remote API access, use the following base URL:
```
https://{pbx_fqdn_domain}
```
Note: To remotely access API via Yeastar FQDN, you need to configure API remote access. For more information, see Configure Network for Remote API Access by a Yeastar FQDN.

{api_path}: The format of API path is openapi/{version}; the {version} indicates the API version.; All URLs referenced in the documentation use API version v1.0, and the API path is openapi/v1.0.

{endpoint}

Endpoint indicates the specific address of API request.

Refer to API Interfaces & Events Summary for all available API endpoints on Yeastar P-Series PBX System.

{access_token}: Access token is used to authenticate API requests. The third-party application should Get Access Token before calling APIs. Each subsequent request requires the access token for authentication.
For detailed API authentication, see Authorization Rule.