Introduction
This document is intended for users who want to develop applications that make use of our PSTN or SMS gateways.
The SpoofTel API is provided for free of charge and requires an active SpoofTel account. Your SpoofTel account is used to validate your requests in order to place calls or send SMS messages.
Currently, only caller ID spoofing is permitted through our API. SMS spoofing will be added in the near future.
Getting Started
Register an account with SpoofTel Ltd.
Be sure to enter in a valid number that we can call you at. When you receive the call, a four digit PIN will be provided that you will need to enter into the site for verification.
After successfully entering in your four digit activation PIN, your account is ready to go and you are able to "POST" data to our API.
Simple API
In order to start a call or send an SMS message, SpoofTel will need to authenticate you as a valid user. To do this, we require a valid username and password passed in all requests made to the API.
API Location: https://www.spooftel.com/API/doCall.php
Please ensure that you send all data via SSL ("HTTPS" not "HTTP"), as data sent unencrypted can be intercepted and potentially put your account at risk.
Output for the API is displayed in XML for easy reading by multiple application platforms.
| Name | Parameter | Short Description | Restrictions |
|---|---|---|---|
| User Name | userName | Valid SpoofTel user name | Alphanumeric, underscore, and between 4 to 19 characters |
| Password | password | Account password | Alphanumeric, underscore, and between 4 to 19 characters |
| Record Call | tapeCall | Record call flag | Set to "Yes" to record the call |
| Voice Change Pitch | voiceChange | Change pitch of caller to pitch specified | Accepts single digit "1" - "7" with "1" being the lowest pitch(male) and "7" being the highest(female). "0", "4" or blank for no change |
| Destination Number's Country Code | tocountrycode | Destination number's country code | Country Code of destination number. No "001" prefix or leading "+" symbol should be used |
| Destination Number | targetNumber | Number to call | A valid format number between 5 - 15 digits |
| Source Number's Country Code | fromcountrycode | Source number's country code | Country Code of source number. No "001" prefix or leading "+" symbol should be used |
| Source Number | fromNumber | Source number | A valid format number between 5 - 15 digits |
| Caller ID Number | callerIDNumber | Caller ID Number to display for call | Digits only, 0 - 15 digits in length |
| Caller ID Name | callerIDName | Caller ID Name to display for call | Alphanumeric, underscores, and spaces allowed. 0 - 15 characters |
| Callback URL | callbackurl | URL to send call detail records to when the call is finished | Must be a valid domain or IP address without HTTP://. Eg: www.spooftel.com/callback.php |
| Time Limit | timelimit | Amout of seconds until the call is hungup | Numeric only, cannot exceed your balance |
| Custom | custom | A user defined variable | Alphanumeric, underscores, and spaces allowed. 255 character max |
Basic API Error Codes
These error codes are generated when our API detects problems with your submission. All output is displayed in XML format for easy parsing.
- ERROR 100: System error. Please try later.
- ERROR 200: $result //invalid user input to/from or caller ID number/name
- ERROR 201: Blank userName received.
- ERROR 202: Blank password received.
- ERROR 300: You do not have enough funds to make this call. Please purchase.
- ERROR 400: Your account is suspended.
- ERROR 500: Service unavailable.
- ERROR 600: You have a call in progress.
Advanced API
Our advanced API allows you to utilize all of SpoofTel's features in one POST. There are slight variations to the POST names provided to our API compared to the "Simple API"
API Location: https://www.spooftel.com/API/doAPI.php
Please ensure that you send all data via SSL ("HTTPS" not "HTTP"), as data sent unencrypted can be intercepted and potentially put your account at risk.
Output for the API is displayed in XML for easy reading by multiple application platforms.
| Name | Parameter | Short Description | Restrictions |
|---|---|---|---|
| User Name | userName | Valid SpoofTel user name | Alphanumeric, underscore, and between 4 to 19 characters |
| Password | password | Account password. | Between 4 to 55 characters |
| Record Call | tapeCall | Record call flag | Set to "Yes" to record the call |
| Voice Change Pitch | voiceChange | Change pitch of caller to pitch specified | Accepts single digit "1" - "7" with "1" being the lowest pitch(male) and "7" being the highest(female). "0", "4" or blank for no change |
| Destination Number Country Code | tocountrycode | Destination number country code. | Country Code of destination number. No "001" prefix or leading "+" symbol should be used. 1 - 4 digits in length |
| Destination Number | targetNumber | Number to call | A valid format number between 5 - 15 digits |
| Source Number Country Code | fromcountrycode | Source number country code | Country Code of source number. No "00" prefix or leading "+" symbol should be used. 1 - 4 digits in length |
| Source Number | fromNumber | Source number | A valid format number between 10 - 20 digits |
| Source Caller ID Number | callerIDFrom | Caller ID Number to display to the source number | Numeric digits only 0 - 15 digits in length. |
| Source Caller ID Name | callerIDFromName | Caller ID Name to display to the source number | Alphanumeric characters and underscores only. 0 - 15 characters |
| Destination Caller ID Number | toCallerIDNumber | Caller ID Number to display to the destination number. | Numeric digits only 0 - 15 digits in length |
| Destination Caller ID Name | toCallerIDName | Caller ID Name to display to the destination number. | Alphanumeric characters and underscores only. 0 - 15 characters |
| Soundboard for call | soundBoard | Select the soundboard to use for this call | Single digit only 2 - 6. Sending 7 uses your custom soundboard. This must be setup prior to making the call |
| Detect Answering Machine | detectAM | Choose whether to play a custom audio file if an answering machine is detected. You must upload your audio file in the "Accounts" menu when logged in | Alphanumeric characters and underscores only. 0 - 15 characters |
| Auto redial | autoRetry | Choose if you want to redial the destination or source if the number is busy | Set to "Yes" to auto redial |
| Callback URL | callbackurl | URL to send call detail records when call is finished. | Must be a valid domain or IP address without HTTP:// Eg: www.spooftel.com/callback.php |
| Time Limit | timelimit | Amout of seconds until the call is hungup | Numeric only, cannot exceed your balance |
| Custom | custom | A user defined variable. | Alphanumeric, Underscores and spaces allowed. 255 character max |
Advanced API Error Codes
These error codes are generated when our API detects problems with your submission. All output is displayed in XML format for easy parsing.
- ERROR 100: System error. Please try later
- ERROR 201: Blank or Invalid userName received
- ERROR 202: Blank password received
- ERROR 203: Source number country code needs to be numeric
- ERROR 204: Destination number's country code needs to be numeric
- ERROR 205: Target number needs to be numeric
- ERROR 207: Source number needs to be numeric
- ERROR 208: Source Caller ID number needs to be numeric
- ERROR 209: Source Caller ID Name needs to be letters numbers or _ (underscore), between 1 and 25 characters
- ERROR 210: Voicechange needs to be numeric
- ERROR 211: Callback URL must be a valid host name or IP address
- ERROR 212: Destination's Caller ID number needs to be numeric
- ERROR 213: Destination's Caller ID Name needs to be letters numbers or _ (underscore), between 1 and 25 characters
- ERROR 214: Custom field needs to be letters, numbers, _ (underscore), or - (dashes) between 1 and 255 characters
- ERROR 215: Timelimit needs to be numeric and between 1 and 4 digits in length
- ERROR 216: Soundboard needs to be numeric
- ERROR 217: Account not found or invalid password used
- ERROR 218: Error loading account
- ERROR 219: Unable to call source number
- ERROR 220: Unable to call destination number
- ERROR 221: Unable to use selected source caller ID number
- ERROR 222: Unable to use selected destination caller ID number
- ERROR 300: You do not have enough funds to make this call. Please purchase
- ERROR 301: The rate for this call exceeds the free call quota. Please signup and purchase credits in order to call these numbers
- ERROR 303: Error determining call rate for destination number
- ERROR 304: Error determining call rate for source number
- ERROR 305: Error determining call rate
- ERROR 300: You do not have enough funds to make this call. Please purchase
- ERROR 400: Your account is suspended
- ERROR 401: Your account is inactive
- ERROR 500: Service unavailable
- ERROR 600: You have a call in progress
- ERROR 900: Free call limit exceeded. Please signup and purchase credits to place more calls.
PHP Example Code
Here is an example using PHP to POST data to our API. The example below is using the account "freecall" which can be used for testing.
<?php
//Variables to POST
$userName = "freecall";
$password = "freecall";
$fromcountrycode = "1";
$fromNumber = "6045551111";
$tocountrycode = "1";
$goingnumber = "6045552222";
$toShowID = "6045555555";
//Set this to your URL that you want the call details sent to.
$callbackurl = "www.example.com/callback.php";
//Set the time limit of this call in seconds.
$timelimit = "60";
//Set this to any alphanumeric value
$custom = "testcall-1234567890";
//Initialize CURL data to send via POST to the API
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://www.spooftel.com/API/doCall.php");
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "userName=$userName&
password=$password&
fromcountrycode=$fromcountrycode&
fromNumber=$fromNumber&
tocountrycode=$tocountrycode&
targetNumber=$goingnumber&
callerIDNumber=$toShowID&
callbackurl=$callbackurl&
timelimit=$timelimit&
custom=$custom"
);
//Execute CURL command and return into variable $result
$result = curl_exec($ch);
//Do stuff
echo "$result"
PERL Example Code
Here is an example using PERL to POST data to our API. The example below is using the account "freecall" which can be used for testing.
#!/usr/bin/perl
use HTTP::Request::Common qw(POST);
use LWP::UserAgent;
use Digest::MD5 qw(md5 md5_hex md5_base64);
#Optional for creating custom field.
$timeDate = localtime(time);
$data=$timeDate.$userName;
$custom=md5_hex $data;
#Set variables for POST
$userName="freecall";
$password="freecall";
$tocountrycode="1";
$targetNumber="6045551111";
$fromcountrycode="1";
$fromNumber="6045552222";
$callerIDNumber="5556664444";
#Set this to your URL to receive the
#Call details once the call has ended.
$callbackurl="www.example.com/callback.php";
#Limit the call time in seconds
$timelimit="60";
#Use LWP to POST data to SpoofTel API
$ua=LWP::UserAgent->new();
my $req= POST 'https://www.spooftel.com/API/doCall.php',
[userName=> $userName,
password=>$password,
tocountrycode=>$tocountrycode,
targetNumber=>$targetNumber,
fromcountrycode=>$fromcountrycode,
fromNumber=>$fromNumber,
callerIDNumber=>$callerIDNumber,
callbackurl=>$callbackurl,
timelimit=>$timelimit,
custom=>$custom];
$content=$ua->request($req)->as_string;
#Return POST response and display
print $content;
PHP Callback URL example
<?php
//Get POST data
$inUserID = addslashes($_POST['userName']);
$fromInput = addslashes($_POST['from']);
$toInput = addslashes($_POST['target']);
$callerIDNumber = addslashes($_POST['callerIDNumber']);
$billedseconds = addslashes($_POST['billsec']);
$ratePerMinute = addslashes($_POST['rate']);
$callRecorded = addslashes($_POST['callrecorded']);
$voiceChanged = addslashes($_POST['voicechanged']);
$custom = addslashes($_POST['custom']);
//Do stuff
echo "Received call details for $custom";
exit();
?>
