REST APIs

Get Started

The PortSIP PBX APIs are HTTP-based RESTful APIs. API request and response bodies are formatted in JSON.

Important:You cannot run the sample requests in this guide as-is. Replace call-specific parameters such as tokens and IDs with your own values.

Authentication and authorization

The PortSIP REST API request ports are as below:

HTTP: 8899

HTTPS: 8900

Example:

  • Assume you have installed your PBX on a server, for which the IP is 216.58.123.206. When you call the REST API, the API base URL should be: http://216.58.123.206:8899/api/ or https://216.58.123.206:8900/api/. You could append the API resource path to the base URL.

  • Assume you have resolved the domain www.bestpbx.com to IP 216.58.123.206, then the API base URL should be: http://www.bestpbx.com:8899/api/ or https://www.bestpbx.com:8900/api/. You could append the API resource path to the base URL.

Before you call any PortSIP PBX REST API, you have to get access token first. You should use Account login API to get the authorization, and PortSIP PBX will issue the access token if the credentials corrected.

The access_token field in the get access token response contains a bearer token:

{
                "access_token": "3BCC13E6F5D34A09B75EC753B433D778",
                "expires": "600",
                "role": "admin",
                "api_version": "9.0.0",
                }
                

You must use this access token in each subsequent request. When a REST API is successfully called then the access token will be refreshed automatically.

Note: You must use refresh token API to refresh the access token before it expires.

Access tokens have a finite lifetime. The expires field in the Account Login API response indicates the lifetime, in seconds, of the access token. For example, an expiry value of 3600 indicates that the access token expires in one hour from the time the response was generated.

Before you create another token, re-use the access token until it expires.

The HTTP methods are:

Method Description
GET Shows details for a resource or lists resources.
POST Creates or manages a resource.

API response

PortSIP PBX API calls return HTTP status codes. Some API calls also return JSON response bodies that include information about the resource.

HTTP status codes

Each REST API request returns a success or error HTTP status code.

Success

In the responses, PortSIP PBX returns these HTTP status codes for successful requests:

Status code Description
200 OK The request succeeded.

Error

In the responses for failed requests, PortSIP PBX returns HTTP 4XX or 5XX status codes.

Update the resource

When you call a PortSIP PBX REST API to update a resource, except the required parameters, other parameters are all optional.

You should not put the parameter as key into the JSON body if you don’t want to update a parameter.