API Documentation Overview

The IP Telecom API documentation discusses concepts and information common to all our API operations. It also contains reference information for each API resource and the API calls that are used to interact with hosted PBX applications.

Common API details

This section discusses the format of our API resources, and the information that is common to each of our API operations, such as authentication, structure, header, errors, status codes, pagination, and timezones.

API Resources
Authentication
Basic URI structure
Headers and metadata
HTTP status codes and errors
Root endpoint
Pagination
Timezone

The API resources section describes each of the hosted PBX API calls in detail and how to execute them. A PBX phone system handles calls, users, devices, callflows, voicemails, call history, and so on. API requests can be used to access and update these PBX resources and perform different types of operations depending on the resource. For each resource, the guide provides the following information:

For full details of API calls, expand the API resources section on the left navigation.

Description and list of API calls

The resource description refers to the information you can get from the API and how you can manage this resource. Under the description of each resource is a list of the API calls or requests you can make associated with this resource.

Endpoints and methods

The HTTP endpoints indicate how you access the resource and the HTTP methods, or verbs, determine what action the API should take with the resource. The IP Telecom accounts API uses the following HTTP request methods:

Endpoint examples:

/v2/accounts/{ACCOUNT_ID}/resources
/v2/accounts/{ACCOUNT_ID}/resources/{RESOURCE_ID} (contains specific resource ID)

HTTP Methods:

PUT: Creates a new instance of the resource.
GET: Gets a summary of configured resources.
POST: Updates the full representation of the resource. (Requires specific resource ID)
GET: Gets the full representation of the resource. (Requires specific resource ID)
DELETE: Deletes the resource. (Requires specific resource ID)

Some resources support the PATCH verb, which allows partial updates instead of requiring the request to include the full version of the document. For example, the "users" resource supports the PATCH method:

Sample patch request

  curl -v -X PATCH \
     -H "Content-Type: application/json" \
     -H "X-Auth-Token: {AUTH_TOKEN}" \
     'http://apps.hostedpbx.ie:8453/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}' \
     -d '{"data":{"vm_to_email_enabled":true}}'

This curl request patches the user's document and sets vm_to_email_enabled to true. All normal validation occurs after patching the document. This feature also means that clients can "patch" or "update" documents with their own data only. If a resource does not support PATCH yet, clients can expect to receive a "405 - Method not allowed" error.

Parameters

Parameters are the keys or attributes that you can pass with the endpoint to influence the response. Each resource has different parameters associated with it, for example, users have name, user_id, phone_number, and so on. Some of the keys are mandatory to get a response, but many are optional. The parameters section of each resource specifies which keys are required.

REST APIs have four types of parameters:

Header parameters: Parameters included in the request header, usually related to authorization.
Path parameters: Parameters within the path of the endpoint, before the query string (?). These are usually set off within curly braces, {user} or {user_id} and are not optional.
Query string parameters: Parameters in the query string of the endpoint, after the ?.
Request body parameters: Parameters included in the request body. Usually submitted as JSON.

Request example

The request example includes a sample request using the endpoint, showing some parameters configured.

Info

Requests and responses shown in the documentation are examples only.

Response example and schema

The response example shows a sample response from the request example. The response schema defines all possible elements in the response. When you submit a request to get a list of resources, the response includes a subset of the attributes for that resource. This is the "summary" representation of the resource. If you need the full set of attributes, you must get the "detailed" representation.

For example, if you request a list of devices in the account, the response contains attributes such as the device_type and the device_name for every device on the list. However, if you request a specific device, the response returns the full set of attributes available for a device.

IP Telecom has multiple APIs that fall under two main categories:

Call management resources
Application resources

Call management resources

API calls related to the phone system and incoming and outgoing voicecalls.

Application resources

API calls related to the applications in the hosted PBX system.

Authentication

All API requests must be authenticated. The IP Telecom API uses token-based authentication where Crossbar generates an authentication token (auth-token) by combining your user credentials and an account identifier. You should send this token as part of the HTTP header with any subsequent requests that require authentication. Any API response will have the auth-token defined in the response JSON as well.

NOTE: The API response headers do not contain the auth-token.

Set up and manage API authentication using the following requests:

Request auth-token
Fetch auth-token information
Recover your password

Request auth-token

This request returns the auth-token.

Send a HTTP PUT request including the required parameters. You must include the encrypted (hashed) version of your username and password, along with an account identifier.

Parameters

The table shows the parameters included in the auth-token request.

Key	Description	Type
`credentials`	Required. A hash of the user's credentials.	string
`account_name`	The account name of the user.	string
`account_realm`	The account realm of the user.	string
`method`	The hash method, `md5` or `sha`. The default is `md5`.	string
`phone_number`	A phone number assigned to the user's account.	string

To create the HTTP PUT request for auth-token:

First, choose the hashing method, either MD5 or SHA to create your credentials hash as follows:

MD5: echo -n "{USERNAME}:{PASSWORD}" | md5
SHA: echo -n "{USERNAME}:{PASSWORD}" | sha

NOTE: Linux has "md5sum" as a built-in command, and Mac OS uses "md5". If you are running MacOS, replace all "md5sum" examples with "md5".

Alternatively, you can use online hash generators MD5, or SHA1.

Hashed example:

echo -n 'john@example.com:m32c6NfqYEt' | md5sum
82a2dc91686ec828a67152d45a5c5ef7  -

Note

You must include the hashed credentials in the HTTP PUT request for auth-token, along with the account identifier. In the Linux response, you must only include the alphanumeric section of the output, removing the spaces and the dash -.

Next, choose one of the following as the the account identifier:

Account name: account_name
SIP realm: realm
A phone number assigned to the account: phone_number

Endpoint and method

PUT /v2/user_auth

Request

curl -v -X PUT \
-H "Content-Type: application/json" \
-d '{"data":{"credentials":"82a2dc91686ec828a67152d45a5c5ef7", "account_name":"john_example", "method":"md5"}}' \
https://apps.hostedpbx.ie:8453/v2/user_auth

Response schema

The table shows the parameters included in the auth-token response:

Key	Description	Type
`{AUTH_TOKEN}`	Required. Your authentication token to include in future requests.	string
`{ACCOUNT_ID}`	The account ID, useful for constructing URIs.	string
`{OWNER_ID}`	The user ID of the owner whose credentials were used to generate this token.	string
`{RESELLER_ID}`	The account's reseller account ID (if any).	string
`{REQUEST_ID}`	The request ID, useful for debugging requests on your installation.	string

Response:

  {
  "auth_token": "{AUTH_TOKEN}",
  "data": {
      "account_id": "{ACCOUNT_ID}",
      "apps": [],
      "is_reseller": true,
      "language": "en-US",
      "owner_id": "{OWNER_ID}",
      "reseller_id": "{RESELLER_ID}"
      },
      "request_id": "{REQUEST_ID},
      "revision": "{REVISION}",
      "status": "success"
      }

Fetch auth-token information

This request returns the information that is encoded in the specified auth-token.

Endpoint and method

  GET /v2/token_auth

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
  https://apps.hostedpbx.ie:8453/v2/user_auth/{AUTH_TOKEN}

Response

  {
    "data": {
        "account_id": "{ACCOUNT_ID}",
        "owner_id": "{USER_ID}",
        "method": "cb_user_auth",
        "id": "{AUTH_TOKEN}",
        "reseller_id": "{RESELLER_ID}",
        "is_reseller": false,
        "account_name": "{ACCOUNT_NAME}",
        "language": "en-us",
        "exp": 1573812821
        "apps": [{
            "id": "8bda62bf7ccf8f8acc219d5d2c515376",
            "name": "accounts",
            "api_url": "https://apps.hostedpbx.ie:8453/v2/",
            "label": "Accounts Manager"
            }, {
            "id": "99d5f033f0a4176640f9bf1c4e81abed",
            "name": "numbers",
            "api_url": "https://apps.hostedpbx.ie:8453/v2/",
            "label": "Number Manager"
            }, {
            "id": "0306d5162bad2c7a951b6842483f73cd",
            "name": "voip",
            "api_url": "https://apps.hostedpbx.ie:8000/v2/",
            "label": "Smart PBX"
            }]
            },
            "auth_token": "{AUTH_TOKEN}",
            "status": "success"
            }

NOTE: The "exp" value is a UNIX timestamp that indicates when the current token expires.

Recover your password

This request returns a password reset link to the user's email.

Parameters

The table shows the parameters included in the password recovery request.

Key	Description	Type
`username`	Required. The users's API username string.	string
`account_realm`	The account realm of the user.	string
`phone_number`	A phone number assigned to the users account.	string

Endpoint and method

PUT /v2/user_auth/recovery

Request

    curl -v -X PUT \
        -H "content-type: application/json" \
        -d '{"data":{"username":"API_USERNAME", "account_realm":"ACCOUNT_REALM", "ui_url": "{UI_URL}"}}' \
        https://apps.hostedpbx.ie:8453/v2/user_auth/recovery

Response

    {
        "auth_token": "{AUTH_TOKEN}",
        "data": {},
        "request_id": "{REQUEST_ID}",
        "revision": "{REVISION}",
        "status": "success"
    }

Execute link from email account recovery

This request sends the {RESET_ID} that was collected in the recovery-email.

Endpoint and method

POST /v2/user_auth/recovery

Request

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"reset_id": "{RESET_ID}"}}'
    https://apps.hostedpbx.ie:8453/v2/user_auth/recovery

Response

  Success
  {
      "auth_token": "{AUTH_TOKEN}",
      "data": {},
      "request_id": "{REQUEST_ID}",
      "revision": "{REVISION}",
      "status": "success"
  }
  Unknown {RESET_ID}
  {
      "auth_token": "{AUTH_TOKEN}",
      "data": {
          "user": {
              "not_found": {
                  "cause": "{RESET_ID}",
                  "message": "The provided reset_id did not resolve to any user"
              }
          }
      },
      "error": "500",
      "message": "invalid request",
      "request_id": "{REQUEST_ID}",
      "status": "error"
  }

Basic URI structure

API requests should adhere to the following structure:

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

{VERSION} - This is the version of the API you are calling, you have two options:

a. v1 - Most APIs respond on the v1

b. v2 - A select number of APIs have newer behaviour. If you used its v1 version, then it should work as before.
{ACCOUNT_ID} - Most requests are for a specific account and require the account_id to route the request properly.
{RESOURCE_ID} - When you are accessing a specific resource, such as a device, user, or callflow, the {RESOURCE_ID} points to the specific instance that you are accessing.

Important

IP Telecom recommends only using API v2 for all endpoints, especially when you are also using the hosted PBX UI for that account. The structure of the response in v1 and v2 are similar, however v2 contains pagination and v1 does not.

Headers and metadata

When you are issuing a PUT, POST, or GET request, you must include a request body. When submitting a JSON (the most common body), our API expects to receive a request envelope that contains the following metadata describing the request:

Request envelope

data: This top-level key contains the object you wish to create or update.
auth_token: You can put your auth-token in the envelope, (optional).
verb: The verb is the HTTP request method. You can tunnel a PUT or DELETE in a POST request (optional).

Sample request envelope:

    {
        "data": {
            "create": "user"
        },
        "auth_token": "{AUTH_TOKEN}",
        "verb": "delete"
    }

NOTE: When using PATCH to edit entities, if you want to remove a field from the entity, set it to null:

{
    "data": {
        "update":"this",
        "exists": null
    }
}

This sample request would set update to this and would remove exists from the entity.

Response envelope

Similarly, clients receive the JSON response in an envelope. The response includes some duplicated data from the HTTP response headers because some clients do not have access to those headers.

data: The results of the request (if any).
auth_token: The auth_token used on the request.
status: Displays success, error, or fatal error.
message: Optional message that should clarify what happened on the request.
error: The error code, (if any).
request_id: The ID of the request, useful for debugging the server-side processing of the request.

Sample response envelope

{
    "data": {
        "the": "response",
        "data": "is here"
    },
    "auth_token": "{AUTH_TOKEN}",
    "status": "success",
    "request_id": "{REQUEST_ID}"
}

HTTP status codes

The IP Telecom API provides normal JSON error responses. The table shows typical status and error codes.

HTTP Status Codes	Error message
200 - OK	Successful operation.
201 - Created	The request was created.
202 - Accepted	Operation was accepted for processing, but not completed yet.
400 - Bad request	The request was unacceptable, for example, the request might be missing a required parameter.
401 - Unauthorized	Invalid credentials.
402 - Request failed	The parameters were valid but the request failed.
403 - Forbidden	The API key doesn't have permissions to perform the request.
404 - Not found	The requested resource doesn't exist.
405 - Method not allowed	The requested HTTP method, or verb, is not supported. For example, if a resource does not support a PATCH request.
409 - Conflict	The request conflicts with another request.
429 - Too many requests	Too many requests hit the API too quickly.
500, 502, 503, 504 - Server errors	Something went wrong on our side.

Root endpoint

You can issue a GET request to the root endpoint to get all the endpoint categories that the REST API supports:

curl -v https://apps.hostedpbx.ie

NOTE: In the resources section, the endpoint shows the end path of a resource URL, not the base path common to all endpoints.

Timezone

Timestamps (UTC) are represented in Gregorian seconds. You can convert between UNIX as follows:

UnixEpochInGregorian = 62167219200

gregorian_to_unix($greg) -> $greg - 62167219200

unix_to_gregorian($unix) -> $unix + 62167219200

Pagination

All API list requests in v2 are paginated by default (v1 does not have pagination).

To interpret pagination, see the following CDR pagination example.

CDR pagination request

The following is a typical CDR request for a listing of CDRs:

  curl -v \
      -H "X-Auth-Token: {AUTH_TOKEN}" \
      -H "Content-Type: application/json" \
      http://apps.hostedpbx.ie:8453/v2/accounts/{ACCOUNT_ID}/cdrs

Response

  {
      "auth_token": "{AUTH_TOKEN}",
      "data": [
          {CDR_OBJECT},
          {CDR_OBJECT},
          ...
      ],
      "next_start_key": "g2wAAAACbgUAvn1W1A5tAAAACDk4MDE2ODAwag",
      "page_size": 25,
      "request_id": "{REQUEST_ID}",
      "revision": "{REVISION}",
      "start_key": "g2wAAAACbgUAb0ZX1A5oAWpq",
      "status": "success"
  }

The pagination response keys are next_start_key, page_size, and start_key.

next_start_key: used to get to the next page of results from this API; doesn't appear on the last page.
start_key: used to get back to this page of results (or start pagination from this point).
page_size: the number of results returned in this page.

If no changes are made to the underlying documents, start_key gets you this page of results, and next_start_key directs you to the next page. It performs in a similar way to a linked list.

Setting page size

By default, API requests have a page size of 50 results.

For individual API requests, you can also include a page_size query string parameter. For example: http://apps.hostedpbx.ie:8453/v2/{API_URL}?page_size=25.

Setting sorting order

By default, Crossbar returns the results in descending order. To get results in ascending order either set ascending=true or descending=false in the request query string.

Note

The field used to sort the individual API results depends on the internal implementation of the API endpoint and is not controllable by the client.

Disabling Pagination

If you want to disable pagination for a request, include paginate=false on the query string.