Yay.com loading


Error Sorry


Shopping Basket

Basket Total



Delete everything from your basket?

Go to Checkout
Back to latest posts

VoIP API Beginners Guide Part 1

VoIP 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.

  1. Reseller
  2. User
  3. 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


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


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(

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

if __name__ == '__main__':

Read part II of our beginner's guide here.

Back to latest posts

Blog Archive

ISO 27001 Business Continuity Accreditation ISO 22301 Business Continuity Accreditation Cyber Essentials Certificate of Assurance G-Cloud accredited by the Crown Commercial Service