VoIP Reseller API Beginners Guide Part 1

Whether you simply want to pull your call data down, manage SIP accounts or VoIP Phone numbers, or want to implement our full Cloud PBX service into your own platform, the yay.com API can do it all. Over the next few months, we’ll be publishing a series of guides that will help you get up and running with our API.

This first part will cover: how to access the documentation, in what format commands will be expected, and how to authenticate your requests. Each example will include a working JSON snippet, and a working Python snippet you can execute (these target Python 2.7 and require the requests library (pip install requests)).

Accessing the VoIP API Documentation

We provide comprehensive documentation for our API that covers all the commands you can send to us. The documentation is broken down into groups of commands that affect similar things.

VoIP API Command Formats

The Yay.com API is JSON REST API. For GET and DELETE requests we expect the body of the request to be empty. If one is provided it will be ignored and, in future updates, may trigger an error. For POST requests, you should describe the object you want to create using the JSON fields provided by the documentation. For PUT requests, the whole object must be provided again, not just the fields you wish to update. If fields are left blank they will be set to the default value.

Understanding Authentication

There are two steps to successfully authenticating. The first is to obtain your username and password which can be found in your dashboard. The second step is to whitelist the IP addresses that will be making API calls, for example the IP address of your own servers if you plan to integrate it with your own system. IP addresses can be managed in the dashboard.

Authentication Credentials

The authentication credentials consist of three components.

Reseller
User
Password

There is an additional component you can provide in authentication, this will be discussed in a future part of the guide.

Providing the Credentials

The authentication credentials are sent in the form of extra headers in HTTP requests

X-Auth-Reseller: reseller
X-Auth-User: user
X-Auth-Password: password

Your API request must include a User-Agent header. Requests without one will be rejected.

You can use the /authenticated endpoint to check your credentials are being accepted correctly, this command should return a 200 OK status code followed by the details of your reseller account in JSON format

Request

GET /authenticated HTTP/1.1
X-Auth-Reseller: reseller
X-Auth-User: user
X-Auth-Password: password
Host: api.yay.com
Connection: close
User-Agent: MyAPIApp 1.0

Response

HTTP/1.1 200 OK
Server: nginx/1.10.2
Date: Fri, 16 Dec 2016 13:30:21 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: close
Vary: Accept-Encoding
X-Tracking-Token: 2f45433e-25c6-4955-8687-34e6b328d550

Python Example

The following example shows how to provide your authentication credentials and how to issue a GET request to the /authenticated endpoint to check your credentials are correct.

import requests


def get_authenticated():

    # dict to hold the authentication
    auth_header = {
        u'X-Auth-Reseller': u'reseller',
        u'X-Auth-User': u'user',
        u'X-Auth-Password': u'password'
    }

    # make the API request
    r = requests.get(
        u'https://api.yay.com/authenticated', 
        headers=auth_header
    )

    # print the status code and response body
    print r.status_code
    print r.content


if __name__ == '__main__':
    get_authenticated()

Read part 2 of our VoIP beginner's guide.