Support > Tossable Digits API Documentation

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.


Methods

extensionCreate

Create a new Virtual Number.  To find the Virtual Number you wish to purchase, see numberGetCountries, numberGetRegions, numberGetCities and numberGetTollFree. You'll need this information from these functions to find the correct Virtual Number.

If startdate is not specified, the extension will begin working immediately.  If enddate is not specified, extension will remain in service until manually canceled, either on the website or via the API.

Required
  • apikey
  • forward
  • countryid
    The ISO3166 2-letter Country Code, from numberGetCountries
  • regionid
    The 2-letter US State or Canadian Province, or 'noRegion' from numberGetRegions
  • ratecenter AND/OR city
    NANPA ratecenter name AND/OR city name from numberGetCities

Optional
  • enddate
  • alias
  • didmatch
    You can specify the area code or city code you want. For example, for New York City didmatch of '1718' would make sure you got a 718 area code Virtual Number.
  • startdate

Returns

extensionUpdate

Update an existing extension.  If did is specified and has multiple extensions, an error will be returned.  Field extensionid will guarantee that the correct extension will be updated.  Extensions that are past their enddate will return an error.

Required

Optional

Returns


extensionCancel

Cancel an existing extension.  Effectively does an extensionUpdate and sets enddate to now.  Extensions that are past their enddate will return an error.

Required

Optional
  • extension

Returns

Optional
  • didmatch
  • active -- 0 to show only extensions that have been disconnected, 1 to show only extensions that are currently active.

Returns

Optional
  • extension

Returns

Optional
  • extension

Returns
  • apikey
  • did or extensionid
  • name
    • rtime (Do Not Disturb)
    • outdial (Place outbound calls with Virtual Number as CallerID)
    • screen (Call Screening -- ask caller name before ringing forwarding number)
    • vm (Voicemail)
    • clid (CallerID)
    • callrec (Call Recording)
  • status -- 1 or 0 (On or Off)

Optional

Depending on the name of the feature being set, there are additional optional values that can be passed to control additional aspecs of the feature. When specifying any additional optional value, ALL optional values must be passed.
  • extension
  • When name=rtime
    • start -- Hour to start accepting calls
    • end -- Hour to end accepting calls
    • tz -- Timezone (View POSIX names supported by the Olson tz database)
    • fakering -- Number of seconds to fake ringing outside of Call Accepting hours before playing message/going to Voicemail
    • clipid -- The ID of the audio clip to play.  Defaults to rtimedefault
    • neverforward - 1 or 0 (On or Off). If On, never forwards calls.
  • When name=clid
    • isset -- CallerID when CallerID is available; Valid options: fwd (Forward Callers Number, default), line (Show the Virtual Number), block (block callerid)
    • notset -- CallerID when CallerID is NOT available; Valid options: fwd, line, block
  • When name=vm
    • timeout -- Number of seconds before Voicemail answers. 6 seconds per ring.
    • promptme -- "Press 1 to accept, press 2 to send to voicemail" prompt before connecting call. Avoids calls being sent to forwarding numbers voicemail.
    • email -- 1 or 0 (On or Off). If On, sends voicemail to 'emailTo' value.
    • emailTo -- The email address to send voicemail as an attachment to.
    • clipid -- The ID of the audio clip to play.  Defaults to vmdefault
  • When name=screen
    • clipid -- The ID of the audio clip to play. Defaults to screendefault
  • When name=callrec
    • disablenotify -- 1 or 0 (On or Off). If On, supresses playback of a notification played to both parties that the call being recorded.
    • email -- 1 or 0 (On or Off). If On, sends Call Recordings to 'emailTo' value.
    • emailTo -- The email address to send voicemail as an attachment to.

Returns



Optional
  • extension

Returns
  • apikey
  • did or extensionid
  • vmid -- The VMID from extensionVoicemailGet
  • status -- deleted (only supported status)

Optional
  • extension

Returns
  • No data
  • apikey
  • did or extensionid
  • callbacknum -- The e.164 phone number of the party who is initiating the call.  The phone will ring, and once answered, the person at this number will hear ringing until the calltonum party answers.
  • calltonum -- The e.164 phone number of the party to be called.

Optional
  • extension

Returns
  • No data

audioclipGet

Get the details and file data for the given clipid. File data is base64 encoded by default, and all files are MP3 encoded at 11,025 Hz.

SECURITY NOTE: DO NOT expose this URL directly to your customers. If you do, your API key will be stolen and could steal services and charges that you will be responsible for. We suggest you proxy requests to your customers through your own website, where a request to your website for the audio clip creates a request from your website to our API and streams the data to the customer.

Sample Code (PHP)
<?php 
$res 
unserialize(file_get_contents('http://Sandbox.TossableDigits.com/apihttp.php?apikey=28555a573ff8ece16763db691aae8e62&method=audioclipGet&clipid=999999&format=php_serial'));
file_put_contents('/tmp/xyz.mp3'base64_decode($res['data']['filedata']));
?>
Required

Optional
  • returntype -- Currently only base64 is supported and is used by default

Returns
  • Audioclip Object
  • If the Audioclip has been deleted, the msgs response array will contain a message indicating that the clip is deleted, and filedata will be an empty string.

audioclipNew

Create a new audioclip for use as an outgoing Voicemail, Do Not Disturb or Screening message. File should be in MP3, WAV, AU or UL file, be fairly short, and base64 encoded. We will transcode whatever you upload to the best quality for our internal use. Phones are 8k Hz mono, so consider this when creating your files. You MUST use HTTP POST rather than GET, as GETs only support about 1000-2000 bytes, and most audio files will far exceed that size.

Sample Code (PHP)
<?php 

// You MUST use POST for this API method.

include_once 'HTTP/Request.php';
$r =& new HTTP_Request('http://Sandbox.TossableDigits.com/apihttp.php');
$r->setMethod(HTTP_REQUEST_METHOD_POST);
$postvars = array(
    
'apikey' => '28555a573ff8ece16763db691aae8e62',
    
'method' => 'audioclipNew',
    
'format' => 'php_serial',
    
'clipname' => 'VM: Bob Jones',
    
'filesize' => '284325',
    
'filedata' => base64_encode(file_get_contents('/path/to/file-on-disk.mp3'))
);

foreach(
$postvars as $key => $val) {
    
$r->addPostData($key$val);
}

$reqReturn $r->sendRequest();
if (!
PEAR::isError($reqReturn)) {
    
$res unserialize($r->getResponseBody());
} else {
    
// there was an error in the HTTP call
}

if (
$res['status']) {
    echo 
$res['data']['clipname']; // VM: Bob Jones
} else {
    
// there was an error with the submitted data
}
?>
Required
  • apikey
  • filedata -- Encode the binary data into base64 encoded data
Optional
  • clipname
  • filesize -- If set, will return an error if we decode the base64 data and it does not come out to this value. Highly recommended to use this as an error check.
Returns

audioclipList

Search or List some or all of your audioclips. Returned in order of newest to oldest.

Sample Code (PHP)
<?php 
$res 
unserialize(file_get_contents('http://Sandbox.TossableDigits.com/apihttp.php?apikey=28555a573ff8ece16763db691aae8e62&method=audioclipList&format=php_serial'));
if (
$res['status']) {
echo 
count($res['data']); // The number of Audioclip objects returned.
}
?>
Required

Optional
  • cliptype -- incoming|outgoing|callrec: Voicemails or Voicemail Outgoing Messages or Call Recordings.
  • clipnamesearch -- Search the clipname field. Will search the field for the exact string or substring
  • page -- Which set of 1,000 call records to return. Defaults to 1, the most recent 1,000 calls.

Returns

numberListPool

List all DIDs in the pool.

Required

Optional
  • didmatch
  • status -- inuse, quiet or avail

Returns
  • Array of NumberPool objects

Returns


Returns

Returns

Returns

Optional
  • extensionid or did
  • didmatch

Returns

Optional
  • extensionid or did
  • didmatch -- Searches CallerID and Forwarding Number fields. Note: Use sparingly as this is a costly and slow search.
  • callid -- The ID of the Call desired.
  • page -- Which set of 1,000 call records to return. Defaults to 1, the most recent 1,000 calls.

Returns

Returned Objects

In some cases we return an Object or an Array of objects.  This section describes what will be returned.
Returned by extensionCreate, extensionUpdate, extensionCancel, extensionList, extensionGet.

Field Name Data Type Description
extensionid int Unique Extension ID
did string DID associated with the extension
forward string DID that rings when called
added int Unix timestamp extension was created
startdate int Unix timestamp extension will be/became active
enddate int Unix timestamp extension will be/became disconnected
alias string User-specified string to identify or describe the extension
   

Country

Returned by numberGetCountries.

Field Name Data Type Description
countryid string Two letter ISO3166 Country Code
countryname string Official ISO3166 Country Name
countrycode int Country Dialing Code

Region

Returned by numberGetRegions.

Field Name Data Type Description
regionid string Region ID. US: Two Letter USPS State Abbreviation. CA: Two Letter Canada Post Province Abbreviation. Elsewhere: "noRegion"
regionname string The name of the region

City

Returned by numberGetCities.

Field Name Data Type Description
countryid string Country ID
regionid string Region ID
ratecenter string NANPA Rate Center
city string City Name
prefix string City prefix. In +1 countries, NPA (area code)  Int'l: city code
rate_monthly float Amount billed per month for a number in this location.
rate_setup float Amount billed once for setting up a number in this location.

TollFree

Returned by numberGetTollFree.

Field Name Data Type Description
countryid string Country ID
regionid string Region ID
ratecenter string NANPA Rate Center
city string City Name
prefix string City prefix. In +1 countries, NPA (area code)  Int'l: city code
tftype int 1: US48 non-payphones
rate_monthly float Amount billed per month for a number in this location.
rate_setup float Amount billed once for setting up a number in this location.

CallSummary

Returned by callSummary.

Field Name Data Type Description
firstcall int Unix Timstamp of the start of the first call in the Summary
lastcall int Unix Timestamp of the start of the last call in the Summary
minduration int The shortest call length, in minutes
maxduration int The longest call length, in minutes
avgduration float The average call length, in minutes
totalduration int The total call length, in minutes
totalcalls int The total number of calls

CallRecord

Returned by callRecords.

Field Name Data Type Description
startdate int Unix Timstamp of the start of the call, in UTC/GMT
duration int Call Length billed, in minutes. This may be zero (0) if the call was not billed. The seconds field fordetails on how long the call lasted, regardless of billing status.
extensionid int The internal Extension ID
callednum string The number that was called, i.e. your virtual number
forwardnum string The number the call was forwarded to, if forwarded; 0 if not forwarded
callernum string The number provided by CallerID
callername string The name provided by CallerID (may be the same as callernum)
status string The status of the call
seconds int The duration in seconds of the time elapsed from the time the call was answered by Voicemail or by the forwarding phone until the time the call was hung up
callid string A unique identifier for the call.
cliptype string If an audio clip is associated with the call this field will identify the type of audio clip. If set, the value will either be vm for Voicemail or cr for Call Recording. If no audio clip is associated, this field will be empty.
clipid int The unique clipid to pass to audioclipGet to retrieve the audio clip related to this call. If no audio clip is associated with the call, this field will be 0 (zero).

Feature

Returned by extensionFeatureGet, extensionFeatureSet.

Field Name Data Type Description
status int On (1) or Off (0)
options array Array of key/value pairs
feature string The short name of the feature: screen, vm, rtime, clid, outdial

Voicemail

Returned by extensionVoicemailGet.

Field Name Data Type Description
vmid int Internal Voicemail ID
calleridname string CallerID Name data
callerid string CallerID Number data
callback string The phone number the caller entered as the callback number.
timestamp int Unix Timestamp of the start of the call, in UTC/GMT
length int The voicemail length, in seconds
clipid string The ID of the clip (used to fetch the actual audio)
callid string A unique identifier for the call.

CallRecording

Returned by extensionCallRecordingGet.

Field Name Data Type Description
crid int Internal Call Recording ID
calleridname string CallerID Name data
callerid string CallerID Number data
forwardnum string Phone Number the call was forwarded to
timestamp int Unix Timestamp of the start of the call, in UTC/GMT
length int The Call Recording length, in seconds
clipid string The ID of the clip (used to fetch the actual audio)
callid string A unique identifier for the call.

Audioclip

Returned by audioclipGet, audioclipSet, audioclipNew, audioclipList.

Field Name Data Type Description
clipid int Internal Audioclip ID
clipname string User defined name for the clip
filesize int The size in bytes of the Audioclip
duration int The duration in seconds of the Audioclip
added int Unix Timestamp of the Audioclip creation, in UTC/GMT
cliptype string Either incoming (Voicemail Messages) or outgoing (Outgoing Voicemail/DND/Screening messages)
filedata string Always empty except when returned by audioclipGet. Base64-encoded binary file data. Always mp3 format (audio/mpeg).