Getting started with the API

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

Introduction to the REST API

The API provides access to resources via URL paths. To use it, your application makes an HTTP request and parses the response. Requests and responses are in JSON format, unless a specific endpoint documents otherwise.

The API is based on open standards, so you can use any web development language. For quick access, tools like cURL (for working with HTTP from a terminal) and Postman (a GUI application for HTTP APIs) come in handy.

Prerequisites

The main URL path to the API. If you do not have this URL, ask Support.
An authentication token. Every request must be authenticated, so you need a token before making any other call — see Authenticating with the API.

Accessing REST API resources

API resources live at:

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

To learn about the URL structure, read API Basics.

For now, assume we want to get our own account settings:

curl -X GET \
  -H "X-Auth-Token: {AUTH_TOKEN}" \
  'https://{SERVER}:8443/v2/accounts/{ACCOUNT_ID}'

Breaking that command down:

Part	What it does
`-X GET`	Tells cURL to perform an HTTP GET request.
`-H "X-Auth-Token: …"`	Adds the authentication header the API requires. `{AUTH_TOKEN}` is your token.
`{SERVER}:8443`	The main API URL.
`v2`	The API version.
`accounts`	The name of the resource you want to access.
`{ACCOUNT_ID}`	The specific instance of that resource — here, your own account ID.

Running the command gives 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}"
}