Skip to content

Introduction

Here you will find description of VoIPstudio API, which gives access to all platform resources.

General

The REST API enables VoIPstudio customers to access a wide range of resources. Our API has predictable, resource-orientated URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features like HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application. JSON is returned by all API responses, including errors.

Endpoints

The base URL for the API is:

https://l7api.com/v1.2/voipstudio/

Authentication

Before sending requests to VoIPstudio API you first need to obtain API Key also known as user_token which will be used to authorise all requests.

You can generate API Key / user_token in of the following two ways:

  1. Send POST request to /login endpoint with email and password as credentials.
  2. Use VoIPstudio Web Dashboard to create API Key / user_token.

Please see detailed instructions below:

Login with email and password

Login request using e-mail and password:

curl -X POST -H "Content-Type: application/json" \
     https://l7api.com/v1.2/voipstudio/login \
     -d '{"email":"jsmith@example.com","password":"$ecretPas$$"}'

Example request:

POST /v1.2/voipstudio/login HTTP/1.1
Host: l7api.com
Content-Type: application/json
{"email":"jsmith@example.com","password":"$ecretPas$$"}

Example of successful response:

{
    "message":"Login success",
    "user_token":"123456abc993ba5dd8a0e7ce9876543",
    "user_id":123456
}

By default user_token will expire after 30 minutes of inactivity (ie. no API requests are made). Every time an API request is made expiration timer is reset.

If you require API tokens with longer expiration time, after obtaining initial user_token with POST /login request, additional API keys can be created by sending POST /apitokens:

curl -X POST -H "Content-Type: application/json" \
     -H "X-Auth-Token: 123456abc993ba5dd8a0e7ce9876543" \
     https://l7api.com/v1.2/voipstudio/apitokens \
     -d '{"name":"Example API App","expiry":604800}'

Example of successful response:

{
    "data":{
        "user_id":123456,
        "token":"9843211cb48787655cddb080ebdabced",
        "customer_id":521156,
        "name":"Example API App",
        "host":"8.8.8.8",
        "user_agent":"curl/7.58.0",
        "expiry":604800,
        "last_request_at":null,
        "created_at":"2023-02-09 17:20:01"
    },
    "links":{}
}

Note: to create API Key which will never expire, use "expiry":0 in request payload to POST /apitokens

Web Dashboard - Add API Key

Follow steps below to add API Key for a user:

  1. In Administration panel edit user for whom API Keys needs to be added.
  2. Go to API Keys section.
  3. Enter a name for your API Key, this can be anything you like. For example a name of your application that will use this API Key.
  4. Click "Add" button.
  5. Click "Eye" icon to retrieve the actual API Key / user_token
  6. Click "Gear" icon and select "Show Details" to obtain additional details or delete API Key.

api-key-add.png

Figure 1.1 Add API Key.

Making requests

Incoming requests handled by our API are expected to have a X-Auth-Token header with a value user_token (API Key) returned from a successful POST /login or POST /apitokens response. 

X-Auth-Token: TOKEN

Example of authenticated request:

curl -H "Content-Type: application/json"
     -H "X-Auth-Token: 123abc45678def3234sdfgdf3434df3444" \
     https://l7api.com/v1.2/voipstudio/cdrs

HTTP responses

VoIPstudio REST API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that has failed given the information provided (e.g., a required parameter was omitted, etc.), and codes in the 5xx range indicate a server error.

Each successful response, depending on HTTP method, contains the following properties:

  • GET collection of resources:

    • data - an array of resources data
    • total - total number of resources

  • GET single resource:

    • data - resources data
    • links - links to related resources

Each error response contains the following properties:

  • message - general error message
  • errors - an array of error messages

Pager

For data collection endpoints such as GET https://l7api.com/v1.2/voipstudio/cdrs pager can be used to return a specific number of records from a given page in the data set. To apply pager please append the following parameters to the URL ?page=N&limit=Z where N is a page number and Z is the number of records to be returned (maximum 5000).

Filters

To filter data, the filter parameter can be passed as a URL query string. The value of filter parameter has to be JSON encoded string in the format shown below:

[
   {"property":"_PROPERTY_NAME_","operator":"_OPERATOR_","value":"_SEARCH_VALUE_"},
   {"property":"_PROPERTY_NAME_","operator":"_OPERATOR_","value":"_SEARCH_VALUE_"}
   ...
]

The three tokens above _PROPERTY_NAME_, _OPERATOR_ and _VALUE_TO_SEARCH_ should be interpreted as below:

  • _PROPERTY_NAME_ this can be any property that belongs to particular endpoint object. See "Resources" section below for detailed explanation of data model for each endpoint.

  • _OPERATOR_ can be one of:

    • eq or = when looking for records with "property" value equal to _SEARCH_VALUE_
    • ne, neq, <> or != when looking for records with "property" value NOT equal to _SEARCH_VALUE_
    • lt or < when looking for records with "property" value less than _SEARCH_VALUE_
    • lte or <= when looking for records with "property" value less than or equal _SEARCH_VALUE_
    • gt or > when looking for records with "property" value greater than _SEARCH_VALUE_
    • gte or >= when looking for records with "property" value greater than or equal _SEARCH_VALUE_
    • in when looking for records with "property" value included in _SEARCH_VALUE_ (Note: search value needs to be passed as an array, eg: [ "foo", "bar" ])
    • like when looking for records with "property" value matching pattern of _SEARCH_VALUE_
    • notlike when looking for records with "property" value NOT matching pattern of _SEARCH_VALUE_

  • _SEARCH_VALUE_ the value you want to search for

Example of request to /cdrs endpoint searching for incoming calls (dst_id property equals user Id) to user Id 123456 after 1st Sep. 2018:

curl -G -H "X-Auth-Token: TOKEN" 'https://l7api.com/v1.2/voipstudio/cdrs' \
     --data-urlencode 'filter=[
       {"property":"dst_id","operator":"eq","value":"123456"},
       {"property":"calldate","operator":"gt","value":"2018-09-01 00:00:00"}
     ]'

Grouping

group_by parameter is available for grouping records by specific property: GET https://l7api.com/v1.2/voipstudio/cdrs?group_by=src. This parameter should be passed as URL query string.