Read a quick overview on our API!

Tossable Digits API

The Tossable Digits API allows customers to access, create and cancel services offered by Tossable Digits.  The API accessible using two methods: SOAP and HTTP.  The API keys used to access the API are keyed to a specific user.

To get started, go to the Sandbox Website, http://Sandbox.TossableDigits.com/ in your web browser and log in. It may take up to an hour after you create your account for it to work on the Sandbox server. Once you log in, click Profile and create a new API key. This API key will ONLY WORK on the Sandbox server. When you are ready for production, you can repeat this process on the production website where you'll get a different API key. This separation is to prevent accidental purchase of Virtual Numbers.

HTTP

The HTTP API interface is a simple GET or POST to a URL.  We highly recommend that you use POST rather than get, as a few API calls require POST and will not work using GET. The Response returned is either a JSON object or a serialized PHP string.  Methods are implemented using the method key, with the value being the name of the method as described below.  Response format is controlled by the format key.  Valid values for format are json or php_serial.  If format is not passed, the response defaults to json.  All values must be url encoded. 

The response will be an object that contains 3 values:

• status boolean - FALSE on any errors or failures, TRUE on success.
  
• msgs array - An array of messages, usually error strings, for the given response.  Usually empty if status is TRUE.
• data mixed - Each method may return a unique datatype.  Possible return values are an object, an array, a string or an integer.

The URL for the HTTP API interface:

Production: http://www.TossableDigits.com/apihttp.php
Sandbox: http://Sandbox.TossableDigits.com/apihttp.php

An example valid HTTP call:

http://www.TossableDigits.com/apihttp.php?method=numberGetCities&apikey=28555a573ff8ece16763db691aae8e62&countryid=DK&regionid=noRegion&format=json

An example success response (JSON), with formatting for easy viewing:

{
    "msgs":[],
    "status":true,
    "data":[
        {
            "countryid":"DK",
            "regionid":"noRegion",
            "ratecenter":"NORATECENTER",
            "city":"GEOGRAPHICAL",
            "prefix":"6",
            "rate_monthly":"9.79",
            "rate_setup":0
        }
    ]
}
    

An example error response (JSON):

{"msgs":["Required value forward not set or is empty"],"status":false,"data":null}

An example error response (PHP Serialized String):

a:3:{s:4:"msgs";a:1:{i:0;s:42:"Required value forward not set or is empty";}s:6:"status";b:0;s:4:"data";N;}

Example Code

<?php
// Get Countries
$res = unserialize(file_get_contents('http://Sandbox.TossableDigits.com/apihttp.php?apikey=28555a573ff8ece16763db691aae8e62&method=numberGetCountries&format=php_serial'));
if ($res['status']) {
    $countries = $res['data'];
} else {
    // There was an error.  See $res['msgs'] for the specific error
}
?>

SOAP

The SOAP WSDL is available here:

    Production: http://www.TossableDigits.com/apisoap.php?wsdl
    Sandbox: http://Sandbox.TossableDigits.com/apisoap.php?wsdl

Methods are described below, as are the specific fields.

Example Code

<?php
/** 
 * Get Countries.  
 * Example uses the PHP SOAP Client, http://us.php.net/manual/en/class.soapclient.php
 * Found within the PHP SOAP Library, http://us.php.net/manual/en/book.soap.php
 */
try {
    $soap = new SoapClient('http://Sandbox.TossableDigits.com/apisoap.php?wsdl');

    // To display the functions and their parameter positions, call ();
    $res = $soap->numberGetRegions('28555a573ff8ece16763db691aae8e62', 'US');
    // OR
    $res2 = $soap->__soapCall(
        'numberGetRegions', 
        array(
            'apikey' => '28555a573ff8ece16763db691aae8e62',
            'countryid'  => 'US',
        )
    );
} catch (Exception $e) {
    echo "Exception Error: " . $e->getMessage();
    die();
}

/**
 *  $res now and $res2 should contain the same data
 *  and should be an array of Region objects
 */

print_r($res);

?>

Document Definitions

• The term DID as used in this document describes a E.164 phone number.

• The term extensions in this document describes the provisioning of a DID (virtual phone number) for use.
  

Field Specific Details

Fields used in the API methods are documented here.

• Fields did and forward must include the country dialing code (1 US, 44 UK, etc). We follow the E.164 format, using only numeric values and always including the country dialing code.  For example, a New York, NY number should be passed as 12125004000.  A London, UK number should be passed as 442070403000.
• Field didmatch can be a full phone number, or just the first portion of a number.  For example, if you wanted to see all the extensions in your account for New York, NY 212, you would set didmatch to 1212.
• Field callid is a unique identifier for a call. It is always a 32 character MD5 string.
• Field apikey is always a 32 character MD5 hash, provided by Tossable Digits.  You can create and expire API keys in the Profile section of your account.
• Fields startdate and enddate accept both unix timestamps (number of seconds from the epoch, January 1, 1970 UTC) as well as GNU date input formats (http://www.gnu.org/software/tar/manual/html_node/Date-input-formats.html).  For extensionCreate and extensionUpdate these fields must be greater than or equal to the current time, or an error will be returned.  For callSummary and callRecords startdate must simply be before enddate.
  
• Fields added, startdate and enddate are always returned in unix timestamp format, which is always in UTC (Coordinated Universal Time).
  
• Fields extension and extensionLength allow you to create extensions on a given number, as well as modify the length of extensions.  This is currently not implemented.  Passing these fields will result in an error.
• Field alias is a custom field, accepting 255 characters, allowing a unique string to identify the extension.