ProveOut - Phone Verification and Online Fraud Prevention. Lowest rates.

Introduction

Creating call

Input parameters
Proveout response

Checking call results

Input parameters
Proveout response

Getting phone number description

Input parameters
Proveout response

Downloading voice recordings.

Input parameters
Proveout response

Examples

This document describes how to programmatically interact with the ProveOut website (located at http://www.proveout.com). Interaction of this sort might be useful to those desiring to make verification calls, verify call statuses, get a phone description or download a particular call's record.

This page describes the fields and parameters required for interfacing with the ProveOut system to perform these actions.

You can apply an API to automate your site with the ProveOut phone verification module. Using the API is simple. You need to post a few parameters to the script at the ProveOut website and receive a reply back. The reply contains call_id parameter which is used to track calls later.

Verification call

A verification call may be performed by doing HTML form post of the GET or POST variety to the URL: https://www.proveout.com/cgi-bin/pvs.cgi The following input fields should be used:

Input field	Description
subscriber_id	Required. Your subscriber id at ProveOut.com, i.e.
password	Required. Your subscriber password at ProveOut.com
action	Required. Can be 'call' 'prepare_call' 'proceed_call'
phone_number	Required. Customer phone number including country and area code.
calltype	Optional. Default is 2. calltype = 1. After establishing a connection with a customer, the system plays a greeting message, dictates a certain PIN code consisting of digits and asks the customer to enter these digits using their phone keypad. calltype = 2. After establishing a connection with a customer, the system plays greeting message and asks the customer to enter a certain PIN code presented on the client's website using their phone keypad. calltype = 3. After establishing a connection with a customer, the system plays a greeting message, dictates a certain PIN code consisting of digits and asks the customer to enter this PIN code on the client's website. calltype = 4. This call type is similar to the other types. The difference is in informing the customer about the results of verification by phone by playing a corresponding message (e.g. "You are verified successfully" or "Verification failed") within the verification call right after the customer enters the PIN code. If the PIN codes mismatch, the system gives a second opportunity for the customer to enter a valid PIN code and so on. The number of attempts that the customer gets before verification fails can be set via the API. calltype = 5. The main difference between this call type and the other types is that customers themselves call ProveOut.com in order to pass the verification procedure. We buy a phone number for you. The cost depends on the country where we purchase phone number; for the majority of countries it is about $10 a month. Customers dials the provided phone number, listen to the voice menu and press certain buttons using their phone keypad (enter confirmation code or access code, enter order number or any other information). The call price depends on the country where the dialled phone number is located. We charge the lowest price for the call to this country according to our price list. For example, if your phone number is located in Brazil, a verification call will cost $0.15 as it is the lowest price for this country according to our price list.
call_retries	Optional. Number of call retries. Valid from 1 to 10. Default value - 2 retries.
call_timeout	Optional. Maximum call length in seconds. Default value 90 seconds.
dtmf_code_length	Optional. The length of tone code you expect from the customer. For example you want the customer to confirm Order Number '123456'. In this case you want dtmf_code_length = '6'. If omitted the default value '4' is applied.
dtmf_code	Optional. The subscriber can define the DTMF code value (auto generated by default)
language	Optional. Language of the system voice messages. Default value - en (English).
postback_url	Optional. An url to return customer verification data. After the verification process finished ProveOut will POST to the 'postback_url' result. If omitted you can track the call later in the ProveOut.com members area.
datetime	Optional. Time to call. GMT time in datetime format "YYYY-MM-DD HH:MM:SS". If omitted or zero call will proceed immediately.
call_now	Optional. Set it to 'on' if you want proceed call as soon as your request submitted..
make_voice_record	Optional. Save a voice record of the customer name. You can download it later in a WAV format via the action 'download_record'. Set to '1' to make a voice record.
wait_call_end	Optional. Set to '1' if you need to wait until the call is finished (i.e. to get the result immediately without checking the call status later. May take 1-2 minutes).
nocall_if_voip_suspected	Optional. Default value - 0 (call), if 1 - do not call if the phone number is suspected as VoIP.
include_phone_types	Optional. (Please refer to phone types) This is a space-delimited phone type list. If the called phone type is in the list, the call will proceed even if this type is in the 'exclude_phone_types' parameter. Please note that 'include_phone_types' has a higher priority than 'exclude_phone_types' parameter.
exclude_phone_types	Optional. (Please refer to phone types) his is space delimited phone type list. If called phone type is in the list, call will not proceeded and an error message will be generated. Please note that 'exclude_phone_types' has lower priority than 'include_phone_types' param.
xml	Optional.Set to 'yes' to force Proveout response in XML format. Default response is plain text format.

Parameter	Description
call_id	ProveOut unique call ID. Useful to track verification calls. 16 digits. String.
phone_number	Customer phone number. String.
country_id_by_phone	Country ID ('US', 'UK' etc) for corresponding phone number
phone_description	State, City, or Mobile operator (based on phone number). String.
subscriber_id	8 digits.
dtmf_code	Important: Actual tone code submitted on the phone by your customer.
remote_addr	IP address call queued from (n the security sense). String.
status	Call status. Can be: pending inprogress failed complete Important: calls with 'complete' status means all those calls when the Third Party has picked up the phone and its duration exceeds one second.
dtmf_complete	Indicates received dtmf code status. Can be: pending (not yet anything received) failed (no dtmf received, verification failed) complete (user entered something on their phone)

You receive a plain text response from the ProveOut.com server. It looks like this:

ProveOut.com response

call_id        4467381807793926
status         complete
dtmf_code      6699
dtmf_code_expected      6699
dtmf_complete	complete
phone_number   442071234567
subscriber_id  02942818
remote_addr    192.168.0.10
country_id_by_phone  GB
phone_description    destination: United Kingdom, description: national rate, location: unknown, registrar: BT

XML response example (you need to set xml=yes)

ProveOut.com response


<?xml version='1.0' standalone='yes'?>
<response>
  <call_id>4467381807793926</call_id>
  <country_id_by_phone>GB</country_id_by_phone>
  <dtmf_code>6699</dtmf_code>
  <dtmf_code_expected>6699</dtmf_code_expected>
  <dtmf_complete>complete</dtmf_complete>
  <phone_description>destination: United Kingdom, description: national rate, location: unknown, registrar: BT</phone_description>
  <phone_number>442071234567</phone_number>
  <remote_addr>192.168.0.10</remote_addr>
  <status>complete</status>
  <subscriber_id>02942818</subscriber_id>
  <voip_suspected>no</voip_suspected>
</response>

If postback_url is submitted then ProveOut.com will POST a response separately with the parameters to postback_url.

Checking call results
The call status value may be obtaned by doing an HTML form post of the GET or POST variety to the URL: https://www.proveout.com/cgi-bin/pvs.cgi The following input fields should be used:

Input field	Description
subscriber_id	Required. Your subscriber id at ProveOut.com, i.e.
password	Required. Your subscriber password at ProveOut.com
action	Required. Must have the value 'status'.
call_id	Required. ProveOut unique call ID. 16-digits.

You receive a plain text response from the ProveOut.com server. It looks like this:

ProveOut.com response

call_id        4467381807793926
status         complete
dtmf_code      6699
phone_number   442071234567
subscriber_id  02942818
remote_addr    192.168.0.10
country_id_by_phone  GB
phone_description    destination: United Kingdom, description: national rate, location: unknown, registrar: BT

Phone number description
The phone number description may be obtaned by doing an HTML form post of the GET or POST variety to the URL: https://www.proveout.com/cgi-bin/pvs.cgi The following input fields should be used:

Input field	Description
subscriber_id	Required. Your subscriber id at ProveOut.com, i.e.
password	Required. Your subscriber password at ProveOut.com
action	Required. Must have the value 'phone_description'.
phone_number	Required. ProveOut unique call ID. 16-digits.

You receive a plain text response from the ProveOut.com server. It looks like this:

ProveOut.com response

numberplan 44870601
country_id_by_phone GB
phone_type XNR
phone_description destination: United Kingdom, description: national rate, location: unknown, registrar: BT
voip_suspected no

List of the available phone types:

+---------+---------------------------+
| type_id | description               |
+---------+---------------------------+
| COU     | proper                    |
| FIX     | geographic                |
| XPR     | premium rate              |
| SAC     | short code                |
| XTF     | freephone                 |
| MOB     | mobile                    |
| WLL     | wireless local loop       |
| AUD     | audiotext                 |
| PAG     | pager                     |
| XSC     | shared cost               |
| ISP     | internet service provider |
| XLR     | local rate                |
| XNR     | national rate             |
| SAT     | satellite                 |
| VPN     | virtual private network   |
| XPN     | personal                  |
| UNI     | universal                 |
| IP      | VoIP telephony            |
| VOI     | voicemail (mobile)        |
| CSC     | carrier selection         |
| VID     | videotext                 |
| VOG     | voicemail (geographic)    |
| PAY     | payphone                  |
| NFX     | national geographic       |
| EMA     | electronic services       |
| TTR     | TETRA mobile services     |
| GTA     | global title address      |
| ADS     | digital subscriber line   |
+---------+---------------------------+

Download record of a call
A call's record value may be downloaded by doing an HTML form post of the GET or POST variety to the URL: https://www.proveout.com/cgi-bin/pvs.cgi The following input fields should be used:

Input field	Description
subscriber_id	Required. Your subscriber id at ProveOut.com, i.e.
password	Required. Your subscriber password at ProveOut.com
action	Required. Must have the value 'download_record'.
call_id	Required. ProveOut unique call ID. 16-digits.

You receive a binary file from the ProveOut.com server.

Examples.

Here is an example of a PERL script. Place it in the /cgi-bin/ directory on your server and try out the demo http://www.yourserver.com/cgi-bin/quick_start.cgi.

quick_start.cgi

#!/usr/bin/perl

use strict;
use warnings;
use LWP::UserAgent;
use CGI qw(param);


my $subscriber_id = '';
my $password = '';
my $pvs_url = 'http://www.proveout.com/cgi-bin/pvs.cgi';


print "Content-Type: text/html\r\n\r\n";

unless (param('action') eq 'call' ) {

print <<HTML;
<html><body>
Please enter your phone number
<form>
<INPUT type="text" name="phone_number">
<INPUT type="submit" name="action" value="call">

</form>
</html></body>
HTML
} else {
        my $phone_number = param('phone_number');
        my $ua    = LWP::UserAgent->new;
        my $req   = HTTP::Request->new(POST => $pvs_url);
        my $post;
        $post .= "action=call" . "&";
        $post .= "phone_number=$phone_number" . "&";
        $post .= "subscriber_id=$subscriber_id" . "&";
        $post .= "password=$password" . "&";
        $post .= "dtmf_code_length=4" . "&";
        $post .= "wait_call_end=1" . "&";
        $post .= "call_now=on";
        $req->content_type('application/x-www-form-urlencoded');
        $req->content($post);
        my $res = $ua->request($req);
        my $reply = $res->content;
        if ($reply =~ /status\scomplete/gs) {

                print "Phone verification successful";
        } else {
                print "Phone verification failed";
        }

}

And some more examples:

Here is an example PERL script you can use to submit a verification call:

subscriber_call.pl


#!/usr/bin/perl
use strict;
use warnings;

use LWP::UserAgent;

my $phone_number = "18003336677";
my $subscriber_id = '';

my $password = '';
my $pvs_url = 'http://www.proveout.com/cgi-bin/pvs.cgi';

my $ua = LWP::UserAgent->new;

my $req = HTTP::Request->new(POST => $pvs_url);

my $post;

$post .= "action=call" . "&";

$post .= "phone_number=$phone_number" . "&";
$post .= "subscriber_id=$subscriber_id" . "&";
$post .= "password=$password" . "&";

$post .= "dtmf_code_length=6" . "&";
$post .= "datetime=2005-12-25 12:44:00" . "&";
$post .= "call_now=on";


$req->content_type('application/x-www-form-urlencoded');
$req->content($post);

my $res = $ua->request($req);

        if (!$res->is_success) {

                print $res->status_line, "\n";
        }
        else {
                print $res->content;
        }

exit(0);

Here is an example PERL script you can use to obtain the status of the verification call:


subscriber_get_status.pl

#!/usr/bin/perl

use strict;
use warnings;
use LWP::UserAgent;

my $subscriber_id = '';

my $password = '';
my $pvs_url = 'http://www.proveout.com/cgi-bin/pvs.cgi';

my $ua = LWP::UserAgent->new;

my $req = HTTP::Request->new(POST => $pvs_url);

my $post;

$post .= "action=status" . "&";

$post .= "subscriber_id=$subscriber_id" . "&";
$post .= "password=$password" . "&";
$post .= "call_class=1413702843944554";


$req->content_type('application/x-www-form-urlencoded');
$req->content($post);

my $res = $ua->request($req);

        if (!$res->is_success) {

                print $res->status_line, "\n";
        }
        else {
                print $res->content;
        }

exit(0);

Here is an example PERL script you can use to download a verification call record (i.e. customers name):

subscriber_download_record.pl

#!/usr/bin/perl

use strict;
use warnings;
use LWP::UserAgent;


my $subscriber_id = '';
my $password = '';
my $pvs_url = 'http://www.proveout.com/cgi-bin/pvs.cgi';

my $call_id = '4250662784227065';

my $ua = LWP::UserAgent->new;
my $req = HTTP::Request->new(POST => $pvs_url);


my $post;

$post .= "action=download_record" . "&";
$post .= "subscriber_id=$subscriber_id" . "&";

$post .= "password=$password" . "&";
$post .= "call_class=$call_id";

$req->content_type('application/x-www-form-urlencoded');

$req->content($post);

my $res = $ua->request($req);

        if (!$res->is_success) {

                print $res->status_line, "\n";
        }
        else {
                open FILE, ">>", "$call_id.wav"

		 or die "cant open $call_id.wav\n";
                print FILE $res->content;
                close FILE;
        }

exit(0);

Here is an example PERL script which can be used for 'postback_url'.

subscriber_postback.pl

#!/usr/bin/perl
use strict;
use warnings;
use CGI qw(param);


my $call_id = param('call_id');
my $phone_number = param('phone_number');

my $subscriber_id = param('subscriber_id');
my $dtmf_code = param('dtmf_code');

my $remote_addr = param('remote_addr');
my $status = param('status');


my $file = '/tmp/proveout_calls.log';

open FILE, ">>", $file or die "cant open $file\n";

print FILE "$call_id\t$phone_number\t$status\t$dtmf_code\n";
close FILE;

print "Content-type: text/plain\r\n\r\n";

print "ok";

Proveout API

Input parameters

ProveOut response

Input parameters

Input parameters

Input parameters

Examples.