FAXAGE Web API Documentation

EC Data Systems, Inc.

Last Revised: September 11, 2009

Lic. US Pats. 4,994,926 5,291,302 5,459,584 6,643,034 6,785,021 7,202,978 7,365,884

Canadian Pats. 1329852 2101327
CONFIDENTIALITY NOTICE

This documentation and all example code provided with it are the confidential and
proprietary property of EC Data Systems, Inc. These materials are provided only for the
purpose of an existing or potential customer evaluating and potentially implementing a
programmatic integration with the FAXAGE Internet fax service. Any other use or
disclosure is strictly prohibited unless the express written consent of EC Data Systems,
Inc. is obtained in advance of such use or disclosure.

EC Data Systems, Inc. Confidential and Proprietary Page 2 of 28

 CONTENTS
Overview ............................................................................................................................. 5
The httpsfax.php URL......................................................................................................... 6
Sendfax Operation........................................................................................................... 7
Supported File Types .................................................................................................. 7
Required POST Variables for Standard Mode............................................................ 8
Required POST Variables for URL Mode .................................................................. 8
Optional POST Variables for Both URL and Standard Modes .................................. 8
Possible Responses...................................................................................................... 9
Status Operation ............................................................................................................ 10
Required POST Variables ......................................................................................... 10
Optional POST Variables.......................................................................................... 10
Possible Responses.................................................................................................... 10
Definition of Status Record Fields ............................................................................ 11
Clear Operation ............................................................................................................. 12
Required POST Variables ......................................................................................... 12
Optional POST Variables.......................................................................................... 12
Possible Responses.................................................................................................... 12
Listfax Operation........................................................................................................... 13
Required POST Variables ......................................................................................... 13
Optional POST Variables.......................................................................................... 13
Possible Responses.................................................................................................... 13
Definition of Listfax Record Fields .......................................................................... 13
Getfax Operation ........................................................................................................... 15
Required POST Variables ......................................................................................... 15
Optional POST Variables.......................................................................................... 15
Possible Responses.................................................................................................... 15
Delfax Operation ........................................................................................................... 16
Required POST Variables ......................................................................................... 16
Optional POST Variables.......................................................................................... 16
Possible Responses.................................................................................................... 16
Stopfax Operation ......................................................................................................... 17
Required POST Variables ......................................................................................... 17
Optional POST Variables.......................................................................................... 17
Possible Responses.................................................................................................... 17
Disabledid Operation..................................................................................................... 17
Required POST Variables ......................................................................................... 17
Optional POST Variables.......................................................................................... 17
Possible Responses.................................................................................................... 17
Enabledid Operation...................................................................................................... 19
Required POST Variables ......................................................................................... 19
Optional POST Variables.......................................................................................... 19
Possible Responses.................................................................................................... 19
The getcdr.php URL.......................................................................................................... 20
Required POST variables .......................................................................................... 20

EC Data Systems, Inc. Confidential and Proprietary Page 3 of 28

 Optional POST variables........................................................................................... 20
Successful return values for the getcdr.php URL ..................................................... 21
Possible error responses for the getcdr.php URL...................................................... 21
The new_provision.php URL............................................................................................ 22
Possible error responses for the new_provision.php URL........................................ 23
The listac operation ....................................................................................................... 24
Required POST variables .......................................................................................... 24
Optional POST variables........................................................................................... 24
Possible Return Values.............................................................................................. 24
The listnpanxx operation............................................................................................... 25
Required POST variables .......................................................................................... 25
Optional POST variables........................................................................................... 25
Possible Return Values.............................................................................................. 25
The listdids operation .................................................................................................... 26
Required POST variables .......................................................................................... 26
Optional POST variables........................................................................................... 26
Possible Return Values.............................................................................................. 26
The provdid operation ................................................................................................... 27
Required POST variables .......................................................................................... 27
Optional POST variables........................................................................................... 27
Possible Return Values.............................................................................................. 27
The deprovdid operation ............................................................................................... 28
Required POST variables .......................................................................................... 28
Optional POST variables........................................................................................... 28
Possible Return Values.............................................................................................. 28

EC Data Systems, Inc. Confidential and Proprietary Page 4 of 28

Overview
The FAXAGE Web API provides capabilities that an application programmer can use to
integrate Fax capabilities into their application utilizing the FAXAGE service as a
backend. The integration itself is accomplished via HTTPS POST operations.

POSTS are sent to the following URLs:

• https://www.faxage.com/httpsfax.php - Fax sending and receiving operations

• https://www.faxage.com/getcdr.php - Call detail record collection
• https://www.faxage.com/new_provision.php - Automated number provisioning

Each of these URLs will be described in this documentation in terms of both required and
optional variables that are sent to the URL in order to accomplish certain operations.
Responses from the FAXAGE system are additionally defined throughout this
documentation in the relevant section.

Example code is supplied in Perl, Java, PHP and Progress for one or more of these
operations. The basic structure (HTTPS POST with a series of required and optional
variables passed in) is essentially the same for all components and operations that can be
performed utilizing the API. Thus an example of every operation in every language is not
supplied.

EC Data Systems, Inc. Confidential and Proprietary Page 5 of 28

The httpsfax.php URL
There are seven basic operations (four for sending and three for receiving) as detailed
below. There are also two ‘other’ operations for enabling and disabling inbound fax
reception on DID’s assigned to your account. Each of these operations is described in
further detail later in this document, as far as required and optional parameters and
possible responses.

Sending-related Operations

1. The ‘sendfax’ operation allows for posting one or more files that will be faxed to
a specified destination. It can also accept a URL rather than file(s) and will
download the specified URL and fax out the HTML content or document that the
URL points to
2. The ‘status’ operation allows for checking status (pending, success, failure) of a
fax that has been sent
3. The ‘clear’ operation allows for deleting status records for faxes that have
completed sending (either success or failed)
4. The ‘stopfax’ operation allows a pending job to be stopped/cancelled

Receiving-related Operations

1. The ‘listfax’ operation allows for listing of currently received faxes

2. The ‘getfax’ operation allows for downloading of a received fax
3. The ‘delfax’ operation allows for deleting a received fax (presumably after it’s
been downloaded)

Other Operations

1. The ‘disabledid’ operation allows for a number to be ‘busied out’ so that faxes
cannot come in to it
2. The ‘enabledid’ operation allows for a number that had been disabled to be re-
enabled (all numbers are enabled for inbound by default when set up)

A debugging URL is also provided that is equivalent to the httpsfax.php URL, except that
it also returns the contents of your POST, so that you can see what our server thinks you
passed us:

https://www.faxage.com/httpsfax-debug.php

EC Data Systems, Inc. Confidential and Proprietary Page 6 of 28

Sendfax Operation

The sendfax-example.pl script provides an example of code that uses this operation.
Examples for the sendfax operation are also provided in Java, PHP and Progress. All of
these can be found under the example-code directory distributed with this zip file.

Note the optional ‘URL Mode’ below. If you wish to POST a URL to be downloaded and
faxed out rather than file data, please use the variables shown rather than the first set of
Required POST Variables which are for the ‘standard’ mode. Note that URL mode will
support faxing the HTML content and will use stylesheets as well as images, etc.
However, any client-side scripting will not be executed by the parser on our end. Any
supported file type (such as a Word document or PDF) may also be passed in URL mode,
provided that these are available at a designated URL. Also, note that HTML passed to
FAXAGE (in standard mode as a file versus URL mode) can contain external hyperlinks
to images, etc. via HTTP or HTTPs as long as the links are absolute (i.e.: begin with
http:// or https://) or images, etc. can be passed as additional files along with the HTML,
depending on developer preference. The sendfax-example-url.pl script is provided as an
example for URL mode versus standard mode.

Supported File Types

As of this writing, the following file types are supported for sending, others may become
available over time, so please check with us if the type of content you wish to send is not
listed here:

Description Extension(s)
JPEG Image JPG, JPEG
Adobe PDF PDF
Adobe PostScript PS
TIFF Image TIF, TIFF
Microsoft Word DOC
Microsoft Word Template DOT
Microsoft Word 2007 DOCX
OpenOffice Writer Doc (Open Document Text) ODT
Rich Text RTF
Microsoft Excel XLS
Microsoft Excel 2007 XLSX
OpenOffice Calc Spreadsheet ODS
Comma-separated CSV CSV
HTML HTM, HTML
Bitmap Image BMP
GIF Image GIF
HP Printer Control Language PCL
Plain Text TXT

EC Data Systems, Inc. Confidential and Proprietary Page 7 of 28

Required POST Variables for Standard Mode

Variable Description
username Assigned FAXAGE username
company Assigned FAXAGE company credential
password Assigned FAXAGE password
recipname Recipient Name – 32 chars max
faxno Fax Number – 10 digits, numeric only
operation Hard coded to ‘sendfax’ (w/o the quotes)
faxfilenames[ ] Array of file names. These must end in a supported extension – see
the table above for a list
faxfiledata[ ] Corresponding array of base64-encoded strings that are the
contents/data of the file in faxfilenames. E.g.: if faxfilenames[0] is
test.doc, then faxfiledata[0] should be the base64-encoded contents
of test.doc

Required POST Variables for URL Mode

Variable Description
username Assigned FAXAGE username
company Assigned FAXAGE company credential
password Assigned FAXAGE password
recipname Recipient Name – 32 chars max
faxno Fax Number – 10 digits, numeric only
operation Hard coded to ‘sendfax’ (w/o the quotes)
faxurl Absolute URL path (beginning with http:// or https://) to the URL
to fax out.

Optional POST Variables for Both URL and Standard Modes

Variable Description
tagname In the header of each fax page, this specifies the name that will
follow From: If unspecified, the default for your company will be
used
tagnumber In the header of each fax page, this specifies the fax number that
will follow tagname. 14 characters max. If unspecified, the default
for your company will be used
em_notify If this variable is set to 1, then the final status of the job will be
pushed via email to the email address associated with the user

EC Data Systems, Inc. Confidential and Proprietary Page 8 of 28

 credentials that submitted the job. This can be used as an alternative
to polling for status through the API. The format of the email is the
JOBID (see ‘possible responses’ below) in the subject line and the
body will contain the same record format as would be provided by
the ‘status’ operation (see the <StatusRecord> format definition in
the ‘status’ operation section of this document)

Possible Responses

Response Meaning
ERR01: Database connection failed Internal FAXAGE error
ERR02: Login incorrect One or more of username, company,
password is incorrect or your account is
disabled for some reason
ERR03: No files to fax No valid files where found in faxfilenames[
] and/or faxfiledata[ ]
ERR04: Fax number <number> appears to The faxno variable does not contain a 10-
be invalid digit numeric only string
ERR05: <reason> The number you tried to fax to was blocked
(outside of continental US, Canada and
Hawaii or a 555, 911, or other
invalid/blocked type of number)
JOBID: <numeric-job-id> Successful send. The jobid reported can
later be used to get status, etc. for this job
ERR08: Unknown operation specified or Either operation is not correctly hard coded
bad POST <POST contents> or the POST was bad, the POST contents
are returned for debugging purposes
ERR15: Invalid Job ID Internal FAXAGE error – the job was not
properly inserted into our database

EC Data Systems, Inc. Confidential and Proprietary Page 9 of 28

Status Operation

The status-example.pl script provides an example of code that uses this operation.

Required POST Variables

Variable Description
username Assigned FAXAGE username
company Assigned FAXAGE company credential
password Assigned FAXAGE password
operation Hard coded to ‘status’ (w/o the quotes)

Optional POST Variables

Variable Description
jobid If specified, reports only the status of the requested jobid, otherwise
reports status of all jobids for your company
jobids[] Alternative to ‘jobid’ to request status for an array list of jobs as
opposed to a single job
pagecount Hard code this variable to ‘1’. If passed, this will cause the page
count to be displayed as the last field on each status record. If not
passed, then page counts will not be displayed.
useronly Hard code to ‘1’. If passed, the status call will only show records
pertaining to faxes sent by the calling username, versus showing all
records for the account, which is the default mode of operation.

Possible Responses

Response Meaning
ERR01: Database connection failed Internal FAXAGE error
ERR02: Login incorrect One or more of username, company, password is
incorrect or your account is disabled for some
reason
ERR06: No jobs to display or job id The jobid you passed was not found or there are
specified not found simply no jobs to report for your company at this
time
<StatusRecord> The format of the status record(s) returned is as
follows (newline separation if multiple records).
See below for definition of each field

<jobid><tab><commid><tab><destname><tab><
destnum><tab><shortstatus><tab><longstatus><ta
b><sendtime><tab><completetime><tab><xmitti

EC Data Systems, Inc. Confidential and Proprietary Page 10 of 28

 me>(OPTIONAL: <tab><pagecount>)

See the pagecount optional variable above – A

page count may be passed as a final field
ERR08: Unknown operation Either operation is not correctly hard coded or the
specified or bad POST <POST POST was bad, the POST contents are returned for
contents> debugging purposes

Definition of Status Record Fields

jobid – The numeric jobid returned by sendfax originally

commid – Communications job identifier. Useful for support debugging

destname – The destination name

destnum – The destination fax number

shortstatus – One of ‘pending’, ‘success’ or ‘failure’

longstatus – Descriptive failure reason or other descriptive text about the status. NOTE:
This text is intended to be human-readable and is subject to change, programmatic
parsing or rendering of the ‘longstatus’ field is not recommended

sendtime – Time this job was submitted YYYY-MM-DD HH:MM:SS format

completetime – Time this job was completed YYYY-MM-DD HH:MM:SS format, all
0’s if the job is pending

xmittime – Transmit time for this job

pagecount – Optional if the pagecount variable is POSTed. This will display the number
of pages in the job

EC Data Systems, Inc. Confidential and Proprietary Page 11 of 28

Clear Operation

The clear-example.pl script provides an example of code that uses this operation. Clear
will only clear records of completed jobs (presumably after the programmer has
processed them using the status operation). Pending jobs cannot be cleared through the
API.

Required POST Variables

Variable Description
username Assigned FAXAGE username
company Assigned FAXAGE company credential
password Assigned FAXAGE password
operation Hard coded to ‘clear’ (w/o the quotes)
jobid The jobid to clear the status record for

Optional POST Variables

None

Possible Responses

Response Meaning
ERR01: Database connection failed Internal FAXAGE error
ERR02: Login incorrect One or more of username, company, password is
incorrect or your account is disabled for some
reason
ERR07: Job ID: <jobid> not found, The jobid you passed was not found, is not a job
does not belong to you or is for your company or is in a pending state
pending and cannot be cleared yet
<jobid> cleared Successful clear of the specified jobid’s status
record
ERR08: Unknown operation Either operation is not correctly hard coded or the
specified or bad POST <POST POST was bad, the POST contents are returned for
contents> debugging purposes

EC Data Systems, Inc. Confidential and Proprietary Page 12 of 28

Listfax Operation

The listfax-example.pl script provides an example of code that uses this operation.

Required POST Variables

Variable Description
username Assigned FAXAGE username
company Assigned FAXAGE company credential
password Assigned FAXAGE password
operation Hard coded to ‘listfax’ (w/o the quotes)

Optional POST Variables

Variable Description
useronly Hardcode to ‘1’. If specified only shows faxes that the currently
passed credentials (if a non-manager account is being used) has
access to from a website-security perspective. This allows
automatic filtering on a per-user basis when using the API if it is
desirable to control user access on the FAXAGE side versus
building your own capabilities to filter faxes into your application
idasc Hardcode to ‘1’. Causes faxes to be listed by faxid (see listfax
record definition below) ascending. Faxid is an incremented
numeric field, so this is basically an ‘oldest to newest’ type of
listing. The default is to list by the receiving number, then by date
received descending (‘newest to oldest’, grouped by receiving fax
number)
filename Hardcode to ‘1’. Causes a fifth returned column, which contains the
internal filename associated with each received fax
starttime Hardcode to ‘1’. If set, causes the start time as well as the received
time to be returned (the recvdate is the receive time in the return
record, which is really the ‘end time’ of the transmission). Using
this, incoming fax duration can be calculated as recvdate - starttime

Possible Responses

Response Meaning
ERR01: Database connection Internal FAXAGE error
failed
ERR02: Login incorrect One or more of username, company, password is

EC Data Systems, Inc. Confidential and Proprietary Page 13 of 28

 incorrect or your account is disabled for some reason
ERR11: No incoming faxes There are no incoming faxes to list for you
available
<Listfax Record> The format of the listfax record(s) returned is as
follows (newline separation if multiple records). See
below for definition of each field:

<recvid><tab><recvdate>(OPTIONAL:
<tab><starttime>)
<tab><CID><tab><DNIS>(OPTIONAL:
<tab><filename>)

The ‘OPTIONAL’ return values above in parentheses

have to do with whether the ‘filename’ and/or
‘starttime’ optional variables are passed.
ERR08: Unknown operation Either operation is not correctly hard coded or the
specified or bad POST <POST POST was bad, the POST contents are returned for
contents> debugging purposes

Definition of Listfax Record Fields

recvid – Numeric ID for this received fax

recvdate – Date/time fax was received YYYY-MM-DD HH:MM:SS format
starttime – Date/time the phone was initially answered for the call in YYYY-MM-DD
HH:MM:SS format
CID – Caller ID (XXX)XXX-XXXX format, will be ‘Unavailable’ if unavailable
DNIS – The phone number the fax came in to (XXX)XXX-XXXX format. Useful for
determining ‘who’ the fax is for if you have multiple phone numbers and use these to
route
filename – The internal filename associated with this fax (e.g.: fax12345.pdf)

EC Data Systems, Inc. Confidential and Proprietary Page 14 of 28

Getfax Operation

The getfax-example.pl script provides an example of code that uses this operation. Note
that faxes will be returned as either PDF’s or TIFF’s, depending on the settings in the
website under ‘Admin’ -> ‘Fax Format’. The default is PDF unless changed.

Required POST Variables

Variable Description
username Assigned FAXAGE username
company Assigned FAXAGE company credential
password Assigned FAXAGE password
operation Hard coded to ‘getfax’ (w/o the quotes)
faxid The numeric ID of the fax to get, retrieved from the listfax
operation

Optional POST Variables

None

Possible Responses

Response Meaning
ERR01: Database connection Internal FAXAGE error
failed
ERR02: Login incorrect One or more of username, company, password is
incorrect or your account is disabled for some reason
ERR12: FAX ID <faxid> not The faxid passed in is invalid or is an ID that does not
found or does not belong to you belong to your company
ERR13: File could not be Internal FAXAGE error
opened
<filedata> Success condition. Headers will be content-type:
application/octet-stream and disposition: attachment, a
unique filename is also supplied in the headers. The
actual data returned will be the binary contents of the
fax itself. This looks just like a website sending a file
to a browser for Open or Save type of operation.
Depending on your company setup, the file will either
be a TIFF image or an Adobe PDF
ERR08: Unknown operation Either operation is not correctly hard coded or the
specified or bad POST <POST POST was bad, the POST contents are returned for
contents> debugging purposes

EC Data Systems, Inc. Confidential and Proprietary Page 15 of 28

Delfax Operation

The delfax-example.pl script provides an example of code that uses this operation.

Required POST Variables

Variable Description
username Assigned FAXAGE username
company Assigned FAXAGE company credential
password Assigned FAXAGE password
operation Hard coded to ‘delfax’ (w/o the quotes)
faxid The numeric ID of the fax to delete, obtained from listfax

Optional POST Variables

None

Possible Responses

Response Meaning
ERR01: Database connection Internal FAXAGE error
failed
ERR02: Login incorrect One or more of username, company, password is
incorrect or your account is disabled for some reason
ERR14: FAX ID <faxid> not The requested faxid either does not exist or is not a fax
found or does not belong to you belonging to your company
<faxid> Deleted Success condition
ERR08: Unknown operation Either operation is not correctly hard coded or the
specified or bad POST <POST POST was bad, the POST contents are returned for
contents> debugging purposes

EC Data Systems, Inc. Confidential and Proprietary Page 16 of 28

Stopfax Operation

The stopfax-example.pl script provides an example of code that uses this operation.

NOTE: Only faxes ‘In Queue’ or ‘Waiting for conversion’ that are not currently
transmitting can be stopped.

Required POST Variables

Variable Description
username Assigned FAXAGE username
company Assigned FAXAGE company credential
password Assigned FAXAGE password
operation Hard coded to ‘stopfax’ (w/o the quotes)
jobid The numeric ID of the fax to delete, obtained from listfax

Optional POST Variables

None

Possible Responses

Response Meaning
ERR01: Database connection Internal FAXAGE error
failed
ERR02: Login incorrect One or more of username, company, password is
incorrect or your account is disabled for some reason
ERR19: JOB ID <jobid> not The requested faxid either does not exist or is not a fax
found or does not belong to you belonging to your company
<jobid> stopped Success condition
ERR18: No jobid specified The ‘jobid’ variable was not specified or did not
contain a numeric job id
ERR20: Job ID - <jobid> - is The jobid is not currently in an ‘In Queue’ or ‘Waiting
not In Queue for conversion’ status and, therefore, is ineligible to be
stopped
ERR21: Job ID - <jobid> - not The jobid is not on the fax server at present and,
found on fax server therefore, cannot be stopped. This may be indicative of
an internal status error within FAXAGE
ERR22: Job ID - <jobid> - is in The jobid is currently being transmitted and, therefore,
transmission cannot be stopped
ERR23: Job ID - <jobid> - General failure to stop. The request is otherwise valid,
failed to stop but just didn’t work
ERR08: Unknown operation Either operation is not correctly hard coded or the

EC Data Systems, Inc. Confidential and Proprietary Page 17 of 28

specified or bad POST <POST POST was bad, the POST contents are returned for
contents> debugging purposes

Disabledid Operation

The enable-disable-example.php script provides an example of code that uses this

operation and the enabledid operation. ‘Disabling’ a DID causes all calls to that DID to
receive a fast-busy signal. Enabling a DID turns it back on for faxes to come in. All DIDs
are enabled by default when initially set up on FAXAGE.

Required POST Variables

Variable Description
Username Assigned FAXAGE username
Company Assigned FAXAGE company credential
Password Assigned FAXAGE password
Operation Hard coded to ‘disabledid’ (w/o the quotes)
didnumber The 10-digit did to disable

Optional POST Variables

None

Possible Responses

Response Meaning
ERR01: Database connection Internal FAXAGE error
failed
ERR02: Login incorrect One or more of username, company, password is
incorrect or your account is disabled for some reason
ERR17: DID <didnumber> not The requested didnumber either does not exist or is not
found or doesn't belong to you a number belonging to your company
ERR16: invalid DID number - The value of the ‘didnumber’ variable is not a 10-digit
<didnumber> number or was not specified
Disabled <didnumber> Success condition
ERR08: Unknown operation Either operation is not correctly hard coded or the
specified or bad POST <POST POST was bad, the POST contents are returned for
contents> debugging purposes

EC Data Systems, Inc. Confidential and Proprietary Page 18 of 28

Enabledid Operation

The enable-disable-example.php script provides an example of code that uses this

operation and the disabledid operation. ‘Disabling’ a DID causes all calls to that DID to
receive a fast-busy signal. Enabling a DID turns it back on for faxes to come in. All DIDs
are enabled by default when initially set up on FAXAGE.

Required POST Variables

Variable Description
Username Assigned FAXAGE username
Company Assigned FAXAGE company credential
Password Assigned FAXAGE password
Operation Hard coded to ‘enabledid’ (w/o the quotes)
didnumber The 10-digit did to enable

Optional POST Variables

None

Possible Responses

Response Meaning
ERR01: Database connection Internal FAXAGE error
failed
ERR02: Login incorrect One or more of username, company, password is
incorrect or your account is disabled for some reason
ERR17: DID <didnumber> not The requested didnumber either does not exist or is not
found or doesn't belong to you a number belonging to your company
ERR16: invalid DID number - The value of the ‘didnumber’ variable is not a 10-digit
<didnumber> number or was not specified
Enabled <didnumber> Success condition
ERR08: Unknown operation Either operation is not correctly hard coded or the
specified or bad POST <POST POST was bad, the POST contents are returned for
contents> debugging purposes

EC Data Systems, Inc. Confidential and Proprietary Page 19 of 28

The getcdr.php URL
The getcdr.php URL provides an interface that allows for pulling call detail records from
the FAXAGE system. This can be used by service providers for generating downstream
billing or by clients who wish to have realtime CDR access for internal purposes
(chargeback, accounting or usage monitoring, for example).

The getcdr.php functionality works by sending an HTTPS POST to

https://www.faxage.com/getcdr.php with the following variables in the POST. Example
code for this URL is provided under the ‘PHP’ example code directory distributed with
this documentation.

Required POST variables

Variable Name Value

Username Assigned FAXAGE username
Company Assigned FAXAGE company credential
Password Assigned FAXAGE password

Optional POST variables

NOTE: Although these parameters show as optional, one of either of these should be
specified (otherwise all records are returned, which could be a lengthy operation):
• Both begin and end
• ‘nuidgt’ (generally used in conjunction with ‘nuidshow’)

Variable Name Value

Begin Timestamp in YYYY-MM-DD HH:MM:SS format from which
records are to begin
End Timestamp in YYYY-MM-DD HH:MM:SS format from which
records are to end
Nuidshow Utilized with the ‘nuidgt’ variable, this one shows the optional
numeric unique ID for each call detail record (which can then
be specified using the nuidgt variable for subsequent queries).
Hardcode this to ‘1’ to use
Nuidgt Numeric unique ID for which only records greater than the
value passed should be returned. Should be set to the highest
prior numeric unique id that was returned, as these are always
numerically incremented over time

EC Data Systems, Inc. Confidential and Proprietary Page 20 of 28

Successful return values for the getcdr.php URL

The return record format looks like this if nuidshow is not set (begin/end are used).
Records are newline-separated and comma-delimited within each record:

calldate,direction,src,dst,duration

If nuidshow is set to ‘1’, then the format looks like this:

nuid,calldate,direction,src,dst,duration

Where:

Nuid – Numeric unique ID

Calldate – date/time of call start in YYYY-MM-DD HH:MM:SS format
Direction – One of ‘IN’ for inbound calls or ‘OUT’ for outbound calls
Src – The ‘source’ of the call. Caller ID number, basically
Dst – The ‘destination’ of the call. For outbound, this is the dialed number and for
inbound this is the receiving fax number
Duration – Billable call duration (pickup to hangup) in seconds for this call record

In either case, records are ascending-sorted by calldate.

Possible error responses for the getcdr.php URL

Response Meaning
ERR01: database connection failed Internal FAXAGE error
ERR02: login incorrect One or more of username, company or
password is invalid or the account is
currently locked out

EC Data Systems, Inc. Confidential and Proprietary Page 21 of 28

The new_provision.php URL
The new_provision.php URL provides an interface that allows for assigning fax numbers
from the FAXAGE system to your account. All numbers are provisioned as ‘virtual
numbers’ tied to your account. This can be used by service providers or larger clients
looking to automate number provisioning for end-users.

The new_provision.php functionality works by sending an HTTPS POST to

https://www.faxage.com/new_provision.php. The following are the basic modes of
operation:

• ‘listac’ returns a list of area codes in which numbers are available for provisioning
• ‘listnpanxx’ returns a list of NPANXX’s (first 6 digits of the phone number) in
which numbers are available for provisioning
• ‘listdids’ returns a list of available DIDs for provisioning
• ‘provdid’ provisions a specific DID to your account
• ‘deprovdid’ de-provisions (removes) a specific DID from your account

A typical workflow (if using this for user self-signup), might be:

1. Call listac and give the user a list of area codes

2. User picks an area code
3. Call listnpanxx and give the user a list of localities within the area code they
picked
4. User picks an NPANXX
5. Call listdids and give the user a list of DID’s they can choose from
6. User picks a DID
7. Call provdid and provision the selected DID to your account on the user’s behalf

Example code for this URL is provided under the ‘PHP’ example code directory
distributed with this documentation. The ‘listdids’ and ‘provdid’ functions are shown in
the example.

EC Data Systems, Inc. Confidential and Proprietary Page 22 of 28

Possible error responses for the new_provision.php URL

These responses apply to all possible operations. Operation specific error responses and
success cases are documented under each operation separately.

Response Meaning
ERR01: database connection failed Internal FAXAGE error
ERR02: login incorrect One or more of username, company or
password is invalid or the account is
currently locked out
ERR03: unknown operation The ‘operation’ variable is not specified or
does have one of the valid operations as its
value

EC Data Systems, Inc. Confidential and Proprietary Page 23 of 28

The listac operation

This operation lists available area codes for provisioning.

Required POST variables

Variable Name Value

username Assigned FAXAGE username
company Assigned FAXAGE company credential
password Assigned FAXAGE password
operation Hard code to ‘listac’

Optional POST variables

None

Possible Return Values

A newline separated list of area codes in which the system has DID’s available for
provisioning. E.g.:

202
303
415
….

EC Data Systems, Inc. Confidential and Proprietary Page 24 of 28

The listnpanxx operation

This operation lists NPANXX’s (first six digits of a phone number) available for
provisioning.

Required POST variables

Variable Name Value
username Assigned FAXAGE username
company Assigned FAXAGE company credential
password Assigned FAXAGE password
operation Hard code to ‘listnpanxx’

Optional POST variables

Variable Name Value

ac If passed and set to an area code, the returned npanxx list will only be
for the area code passed (the default, if this variable is not passed, is
to return all npanxx’s available)

Possible Return Values

A list of npanxx’s in which the system has DID’s available for provisioning or nothing if
the ‘ac’ value was passed and it is not an Area Code in which DID’s are available.

The return records are newline separated and are in the following format:

<npanxx><tab><rcname><tab><rcstate>

Where:
npanxx – The first six digits of a telephone number
rcname – The Ratecenter name associated with this NPANXX (locality, like ‘Denver’ or
‘San Francisco’, etc.)
rcstate – The state in which the Ratecenter is located for this NPANXX

Note that for toll-free DID’s, both rcname and rcstate will be ‘Toll-Free’

An example returned value would be:

303991<tab>Denver<tab>CO

EC Data Systems, Inc. Confidential and Proprietary Page 25 of 28

The listdids operation

This operation lists DID’s (full telephone numbers) available for provisioning.

Required POST variables

Variable Name Value

username Assigned FAXAGE username
company Assigned FAXAGE company credential
password Assigned FAXAGE password
operation Hard code to ‘listdids’

Optional POST variables

Variable Name Value

ac Set to an area code (three digits), this will cause the list to only
contain DIDs in the specified area code (all DIDs are returned by
default)
npanxx Set to an NPANXX (six digits), this will cause the list to only
contain DIDs in the specified NPANXX (all DIDs are returned by
default). Also, npanxx will override area code if both are passed,
because it is more specific

Possible Return Values

A newline separated list of DIDs (full telephone numbers) available for provisioning, for
example:

3035551212
3035551234
3035551111
….

EC Data Systems, Inc. Confidential and Proprietary Page 26 of 28

The provdid operation

This operation provisions a DID (adds a telephone number to your account).

Required POST variables

Variable Name Value

username Assigned FAXAGE username
company Assigned FAXAGE company credential
password Assigned FAXAGE password
operation Hard code to ‘provdid’
didnumber The 10-digit number to provision

Optional POST variables

None

Possible Return Values

Return Value Meaning

ERR04: Invalid DID number, The ‘didnumber’ variable was not set to a 10-digit
<didnumber> number
ERR05: <didnumber> does Either you have specified a DID that doesn’t exist or it is
not appear to be available already assigned to someone and is not available for
provisioning
<didnumber> provisioned This is the successful response case

EC Data Systems, Inc. Confidential and Proprietary Page 27 of 28

The deprovdid operation

This operation de-provisions a DID (removes a telephone number from your account).

Required POST variables

Variable Name Value

username Assigned FAXAGE username
company Assigned FAXAGE company credential
password Assigned FAXAGE password
operation Hard code to ‘deprovdid’
didnumber The 10-digit number to de-provision

Optional POST variables

None

Possible Return Values

Return Value Meaning

ERR04: Invalid DID number, The ‘didnumber’ variable was not set to a
<didnumber> 10-digit number
ERR05: <didnumber> is invalid or does The ‘didnumber’ either doesn’t exist or is
not belong to you not currently assigned to your account
<didnumber> deprovisioned This is the successful response case

EC Data Systems, Inc. Confidential and Proprietary Page 28 of 28