Connecting to the API

To connect to our API, you need to POST a JSON request to our API endpoint at https://live.apicontrol.co.uk/1/json

For testing your integration without affecting live services, you may wish to use our test API endpoint, which is https://test.apicontrol.co.uk/1/json. This behaves the same way as the live API but uses a different copy of the database. The live API database is mirrored over to the test API database each day at 4am UK local time.

If you are using Perl or PHP, you can also use one of our pre-built client modules that does this part for you and presents an object orientated interface.

JSON request structure

The request structure consists of 3 parts:

• an auth object - this contains authentication data (username, password and an optional env object that can contain additional options)
• a func string - specifying the function/method to call
• an args object containing the arguments to pass to the chosen function

A success response consists of:

• a success value of 1
• a results section containing returned data

A failure response consists of:

• a success value of 0
• an errornum dotted decimal string
• an error string
• an errordiags object containing further information

Example request (note that the indentation and newlines are not required but are instead shown here for reasons of clarity).

This request is requesting a list of all phone numbers on your account that begin with the digits 016 (see number-formatting)

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
   "auth" : {
      "username" : YOURUSERNAME,
      "password" : YOURPASSWORD,
   },
   "func" : "telecoms.num.list",
   "args" : {
      "number.starts" : "016"
   }
}

JSON example response:

{
   "results" : {
      "totmatches" : 1,
      "numbers" : [
         {
            "transport_in" : [
               "pstn"
            ],
            "ivrID" : 3,
            "number" : "01603315641",
            "numberID" : 821001,
            "telco" : "Barritel",
            "valid_to" : "2038-01-19 03:14:07",
            "automated" : 1,
            "tnID" : 0,
            "custID" : 16526,
            "setup_fee" : "0.00",
            "routeto_type" : "ivr",
            "date_alloc" : "2010-09-09",
            "svcchg_optionID" : 0
         }
      ]
   },
   "success" : 1
}

Example of an unsuccessful request (in this instance getting one of the argument names wrong).

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
   "auth" : {
      "username" : YOURUSERNAME,
      "password" : YOURPASSWORD,
   },
   "func" : "telecoms.num.list",
   "args" : {
      "lemmings" : "016"
   }
}

JSON example response:

{
   "success" : 0,
   "results" : {},
   "errordiags" : {
      "arg" : "lemmings",
      "errtype" : "perm",
      "errclass" : "syntax"
   },
   "error" : "unrecognised argument: lemmings",
   "errornum" : "5.1.72"
}