Yay.com loading

Loading

VoIP API Beginners Guide Part 1

Back to latest posts
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 the API.

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

Accessing the VoIP API Documentation

We provide comprehensive documentation for the API that covers all of the commands you can send to us, the documentation is broken down into groups of commands that effect 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 ignored, in future updates this 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 out 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, these 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

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 follow 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()

Geoff

Posted by Geoff

Senior Analyst Developer at Yay.com

Back to latest posts

1 All 01, 02 & 03 numbers. Off peak is 7pm - 7am weekdays & all weekend. All major UK & EU operators. 0845 and other premium or mobile operators may vary. Please use the number search to be absolutely certain of the cost that your call will incur. Unlimited EU calling is available to all major landline and mobile network operators in the European Union with the exception of Austria, Croatia, Estonia, Latvia, Lithuania. Fair usage terms apply.