Skip to content
BrightPBX

Getting started with the API

Warning: The API offers powerful capabilities that can significantly affect your system configuration. If not used with extreme care, there is a high potential to corrupt your setup. Restoring a system damaged due to improper API usage may incur additional costs. Please exercise caution when utilizing the API to prevent any unintended consequences. 

Our API gives you the tools to develop high-quality unified telecom applications. The REST API interface provides a simple way for external application to talk to the platform by making HTTP requests.Introduction to the REST APIs

The APIs provide access to resources via URL paths. To use a REST API, your application will make a HTTP request and parse the response.

Almost most of the time requests and responses for the endpoints are in JSON format, unless other format are expected for specific endpoint which you can find in the documentation.

The REST API is based on open standards like JSON (for data validation). You can use any web developer language to work with the API. Although for quick access to API tools like cURL (to work with HTTP protocol from terminal) and Postman (A GUI application to work with HTTP APIs) are come in handy.

Prerequisites

Before you begin you need to know the main URL path to the API. If you don’t have this URL ask Support.

The API requires the request to be authenticated, so you have to first get an authentication token before making any HTTP request to the API. The are various way to get this authentication token, you can learn more about them in the authentication article.

Accessing to REST API resources

API resources are available at below location:

/{VERSION}/accounts/{ACCOUNT_ID}/resources/{RESOURCE_ID}

To learn about URL structure read REST API Basics.

But for now we assume we want to get out own account settings. For doing this we can simply use this cURL command:

$ curl -x GET -H “X-Auth-Token: {AUTH_TOKEN}” ‘https://{SERVER}:8443/v2/accounts/{ACCOUNT_ID}’

Here the explanation of the command:

  • -x GET is telling cURL to perform a HTTP GET request.
  • -H “X-Auth-Token: {AUTH_TOKEN}” is adding a HTTP header to the request. Here we add X-Auth-Token header required by the API for authentication. {AUTH_TOKEN} is your authentication token.
  • https://… part is telling cURL to which URL make the request.
  • {SERVER}:8443 is the main API URL.
  • v2 is the API version.
  • accounts is the name of the resource we want to have access.
  • {ACCOUNT_ID} is a specific instance of this resource we want. Since we want to get our account information (we are using accounts resource here) we give our own account ID.

Running the command above will give us a response like this:

{ “data”: { “timezone”: “America/Los_Angeles”, “reseller_id”: “{RESELLER_ID}”, “realm”: “{ACCOUNT_REALM}”, “name”: “{ACCOUNT_NAME}”, “language”: “en-US”, “is_reseller”: false, “descendants_count”: 0, “created”: 63636183145, “caller_id”: { “internal”: { “name”: “My Awesome Office” }, “external”: { “name”: “My Awesome Office” }, “emergency”: { “name”: “My Awesome Office” } }, “blacklists”: [], “available_apps”: [], “id”: “{ACCOUNT_ID}”, “knm_allow_additions”: false, “superduper_admin”: false, “enabled”: true }, “timestamp”: “{TIMESTAMP}”, “version”: “{VERSION}”, “node”: “{API_NODE}”, “request_id”: “{REQUEST_ID}”, “status”: “success”, “auth_token”: “{AUTH_TOKEN}” }

Your response maybe be different from this example, since it depends on your account settings. All values in curly brackets ({}) are depends on your account settings and API server and will be populated with the respective values.