FAXAGE. Internet Fax API Documentation

FAXAGE Internet Fax API Documentation

EC Data Systems, Inc. Last Revised: March 28, 2014

FAXAGE® is a registered trademark of EC Data Systems, Inc. Patent information available at http://www.faxage.com/patent_notice.php © Copyright 2014 EC Data Systems, Inc. All Rights Reserved

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 Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 2 of 35

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 .................................. 9 Optional POST Variables for URL Mode Only ......................................................... 9 Possible Responses ................................................................................................... 10 Callback URL POST Reponse .................................................................................. 10 Status Operation ............................................................................................................ 12 Required POST Variables ......................................................................................... 12 Optional POST Variables ......................................................................................... 12 Possible Responses ................................................................................................... 12 Definition of Status Record Fields ............................................................................ 13 Dlstatus Operation ........................................................................................................ 15 Required POST Variables ......................................................................................... 15 Possible Responses ................................................................................................... 15 DltransOperation ........................................................................................................... 16 Required POST Variables ......................................................................................... 16 Possible Responses ................................................................................................... 16 Clear Operation ............................................................................................................. 17 Required POST Variables ......................................................................................... 17 Optional POST Variables ......................................................................................... 17 Possible Responses ................................................................................................... 17 Listfax Operation .......................................................................................................... 18 Required POST Variables ......................................................................................... 18 Optional POST Variables ......................................................................................... 18 Possible Responses ................................................................................................... 19 Definition of Listfax Record Fields .......................................................................... 19 Getfax Operation ........................................................................................................... 20 Required POST Variables ......................................................................................... 20 Optional POST Variables ......................................................................................... 20 Possible Responses ................................................................................................... 20 Delfax Operation ........................................................................................................... 21 Required POST Variables ......................................................................................... 21 Optional POST Variables ......................................................................................... 21 Possible Responses ................................................................................................... 21 Stopfax Operation ......................................................................................................... 22 Required POST Variables ......................................................................................... 22 Optional POST Variables ......................................................................................... 22 Possible Responses ................................................................................................... 22 Disabledid Operation .................................................................................................... 23 Required POST Variables ......................................................................................... 23

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 3 of 35

Optional POST Variables ......................................................................................... 23 Possible Responses ................................................................................................... 23 Enabledid Operation ..................................................................................................... 24 Required POST Variables ......................................................................................... 24 Optional POST Variables ......................................................................................... 24 Possible Responses ................................................................................................... 24 Portable Operation ........................................................................................................ 25 Required POST Variables ......................................................................................... 25 Optional POST Variables ......................................................................................... 25 Possible Responses ................................................................................................... 25 Listlines Operation ........................................................................................................ 26 Required POST Variables ......................................................................................... 26 Optional POST Variables ......................................................................................... 26 Possible Responses ................................................................................................... 26 The getcdr.php URL ......................................................................................................... 27 Required POST variables .......................................................................................... 27 Optional POST variables .......................................................................................... 27 Successful return values for the getcdr.php URL ..................................................... 28 Possible error responses for the getcdr.php URL ..................................................... 28 The provision.php URL .................................................................................................... 29 Possible error responses for the provision.php URL ................................................ 30 The listac operation ....................................................................................................... 31 Required POST variables .......................................................................................... 31 Optional POST variables .......................................................................................... 31 Possible Return Values ............................................................................................. 31 The listnpanxx operation............................................................................................... 32 Required POST variables .......................................................................................... 32 Optional POST variables .......................................................................................... 32 Possible Return Values ............................................................................................. 32 The listdids operation .................................................................................................... 33 Required POST variables .......................................................................................... 33 Optional POST variables .......................................................................................... 33 Possible Return Values ............................................................................................. 33 The provdid operation ................................................................................................... 34 Required POST variables .......................................................................................... 34 Optional POST variables .......................................................................................... 34 Possible Return Values ............................................................................................. 34 The deprovdid operation ............................................................................................... 35 Required POST variables .......................................................................................... 35 Optional POST variables .......................................................................................... 35 Possible Return Values ............................................................................................. 35

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 4 of 35

Overview The FAXAGE Internet Fax 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/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, Visual Basic (as a Visual Studio 2010 project) 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 Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 5 of 35

The httpsfax.php URL There are nine basic operations (six related to sending and three for receiving) as detailed below. There are also four ‘other’ operations for enabling and disabling inbound fax reception on DID’s assigned to your account, checking portability and listing currently assigned DID’s. 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. sendfax - 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. status - allows for checking status (pending, success, failure) of a fax that has been sent 3. dlstatus - allows for downloading a copy of a sent fax as imaged and sent 4. dltrans – allows for downloading a ‘transmittal page’ PDF (job summary information, plus shrunk-down version of first page) for sent faxes. 5. clear - allows for deleting status records for faxes that have completed sending (either success or failed) 6. stopfax - allows a pending job to be stopped/cancelled Receiving-related Operations 1. listfax - allows for listing of currently received faxes 2. getfax - allows for downloading of a received fax 3. delfax - allows for deleting a received fax (presumably after it’s downloaded) Other Operations 1. disabledid - allows for a number to be ‘busied out’ so that faxes cannot come in to it 2. enabledid - allows for a number that had been disabled to be re-enabled (all numbers are enabled for inbound by default when set up) 3. portable - allows for checking of a phone number as to whether or not FAXAGE can provide service in the rate center in which the number resides. I.e.: whether or not the number is potentially portable to FAXAGE 4. listlines - allows for listing all currently assigned DID’s 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 Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 6 of 35

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 Visual Basic (.NET, VS 2010), Java, PHP and Progress. All of these can be found under the example-code directory distributed with the API 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.

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 JPEG Image Adobe PDF Adobe PostScript TIFF Image Microsoft Word Microsoft Word Template Microsoft Word 2007 OpenOffice Writer Doc (Open Document Text) Rich Text Microsoft Excel Microsoft Excel 2007 OpenOffice Calc Spreadsheet Comma-separated CSV HTML Bitmap Image GIF Image HP Printer Control Language Plain Text

Extension(s) JPG, JPEG PDF PS TIF, TIFF DOC DOT DOCX ODT RTF XLS XLSX ODS CSV HTM, HTML BMP GIF PCL TXT

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 7 of 35

Required POST Variables for Standard Mode Variable username company password recipname faxno operation faxfilenames[ ] faxfiledata[ ]

Description Assigned FAXAGE username Assigned FAXAGE company credential Assigned FAXAGE password Recipient Name – 32 chars max Fax Number – 10 digits, numeric only Hard coded to ‘sendfax’ (w/o the quotes) Array of file names. These must end in a supported extension – see the table above for a list 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 The 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. Use the optional faxurltypes[] array if they are script-supplied (i.e.: the extension of the URL does not match the document type), otherwise HTML content is assumed for all URLs. 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. Variable username company password recipname faxno operation faxurl faxurls[]

Description Assigned FAXAGE username Assigned FAXAGE company credential Assigned FAXAGE password Recipient Name – 32 chars max Fax Number – 10 digits, numeric only Hard coded to ‘sendfax’ (w/o the quotes) Absolute URL path (beginning with http:// or https://) to the URL to be faxed Can be used in place of Faxurl to send an array list of multiple URLs to be faxed

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 8 of 35

Optional POST Variables for Both URL and Standard Modes Variable tagname

tagnumber

em_notify

url_notify

resolution

contrastalgo

priority

Description 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 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. This should be in 1.XXX.XXX.XXXX format 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 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 format definition in the ‘status’ operation section of this document) Set to an absolute URL (beginning with http:// or https://) to have the FAXAGE system POST back the fax job status record when the fax completes. See the ‘Callback URL POST’ section below for a listing of what is posted back. Set to ‘1’ for fine resolution or ‘2’ for hyperfine. If not passed, the fax will use your default account settings (as specified in the website under ‘Admin’ -> ‘Outgoing Fax Settings’ -> ‘Resolution and Retries’) Set to ‘1’ for the default contrast enhancement algorithm or ‘2’ for an algorithm that produces more darkening (useful for lighter scans). The default if not passed is ‘1’ Set to ‘high’ or ‘low’. By default, if this is not passed, the priority is ‘high’. Setting certain faxes to ‘low’ priority allows your other faxes to complete ahead of them by jumping ahead of low priority faxes in your queue. For instance, you could send a batch of faxes as ‘low’ priority, but one-off user faxes as ‘high’, so that they would be able to jump the queue ahead of your batch

Optional POST Variables for URL Mode Only Variable async

Description If this variable is set to 1, then the FAXAGE system will return your jobid immediately and retrieve the URL content specified asynchronously (after your connection is completed). The default is

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 9 of 35

faxurltypes[]

to retrieve the URL before returning If the faxurls[] array is used, this can be passed as well. By default the system determines the filetype of a URL based on its extension and defaults to HTML if unknown (such as an ASP or PHP page being passed). The faxurltypes[] array can contain a list of extensions, corresponding to the indexes in the faxurl[] array. For example, if faxurls[0] is http://www.example.com/download.asp?docid=2 and this URL will return a Word document, then faxurltypes[0] would be set to ‘doc’

Possible Responses Response ERR01: Database connection failed ERR02: Login incorrect

ERR03: No files to fax ERR04: Fax number appears to be invalid ERR05:

JOBID: ERR08: Unknown operation specified or bad POST ERR15: Invalid Job ID

Meaning Internal FAXAGE error One or more of username, company, password is incorrect or your account is disabled for some reason No valid files where found in faxfilenames[ ] and/or faxfiledata[ ] The faxno variable does not contain a 10digit numeric only string 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) Successful send. The jobid reported can later be used to get status, etc. for this job Either operation is not correctly hard coded or the POST was bad, the POST contents are returned for debugging purposes Internal FAXAGE error – the job was not properly inserted into our database

Callback URL POST Reponse If url_notify is passed into the initial sendfax call, then the following variables and values will be posted back to a URL you specify when the fax completes. You will need to set up a web page at the URL you designate in the sendfax call that can handle a POST of the variables listed below and do what you need with the information. It is still possible to poll for status (using the ‘status’ operation) if a callback is missed for any reason.

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 10 of 35

Variable Name jobid commid destname destnum shortstatus longstatus

sendtime completetime xmittime pagecount xmitpages

Value The numeric jobid returned by sendfax originally Numeric communications job identifier The destination name The destination fax number One of ‘pending’, ‘success’ or ‘failure’ 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. Time this job was submitted YYYY-MM-DD HH:MM:SS format Time this job was completed YYYY-MM-DD HH:MM:SS format, all 0’s if the job is pending Transmit time for this job HH:MM:SS format The number of pages in the job The number of pages actually transmitted (once the job is completed – it shows ‘0’ while the fax is in progress)

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 11 of 35

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

Required POST Variables Variable username company password operation

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

Optional POST Variables Variable jobid jobids[] pagecount

useronly

extqueue csid showlogin xmitpages begin end

Description If specified, reports only the status of the requested jobid, otherwise reports status of all jobids for your company Alternative to ‘jobid’ to request status for an array list of jobs as opposed to a single job 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 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 Hard code to ‘1’. If passed, extended queue status will be shown for faxes that are currently in queue Hard code to ‘1’. If passed, will return the remote station ID for completed faxes Hard code to ‘1’. If passed, will show the username corresponding to the credentials that were used to send the fax Hard code to ‘1’. If passed, will show the number of pages actually transmitted Date and time from which status records should begin in YYYYMM-DD HH:MM:SS format Date and time from which status records should end in YYYYMM-DD HH:MM:SS format

Possible Responses Response ERR01: Database connection failed ERR02: Login incorrect

Meaning Internal FAXAGE error One or more of username, company, password is

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 12 of 35

ERR06: No jobs to display or job id specified not found

incorrect or your account is disabled for some reason The jobid you passed was not found or there are simply no jobs to report for your company at this time The format of the status record(s) returned is as follows (newline separation if multiple records). See below for definition of each field < destnum>(OPTIONAL: )

ERR08: Unknown operation specified or bad POST

See the pagecount optional variable above – A page count may be passed as a final field Either operation is not correctly hard coded or the POST was bad, the POST contents are returned for 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. If the extqueue value is passed, then the longstatus will be postfixed with ‘Tries: Status: ’. This can be useful for monitoring what is going with retries on jobs 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 EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 13 of 35

xmittime – Transmit time for this job pagecount – Optional if the pagecount variable is POSTed. This will display the number of pages in the job csid – Optional if the csid variable is POSTed. This will display the CSID (the fax machine identifier) for the station called, if available login – Optional if the showlogin variable is POSTed. This will display the login of the credentials that sent each fax record xmitpages – Optional if the xmitpages variable is POSTed. This will display the number of pages actually transmitted (once the job is completed – it shows ‘0’ while the fax is in progress)

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 14 of 35

Dlstatus Operation Required POST Variables Variable username company password operation jobid

Description Assigned FAXAGE username Assigned FAXAGE company credential Assigned FAXAGE password Hard coded to ‘dlstatus’ (w/o the quotes) The jobid to retrieve

Optional POST Variables Variable viewtype

Description Set to ‘tiff’ or ‘pdf’ (w/o the quotes). If not set, the system returns a TIFF (the native image format).

Possible Responses Response ERR01: Database connection failed ERR02: Login incorrect

ERR06: No jobs to display or job id specified not found ERR24: File is not yet converted

ERR25: File does not exist

< IMAGE DATA>

Meaning Internal FAXAGE error One or more of username, company, password is incorrect or your account is disabled for some reason The jobid you passed was not found or there are simply no jobs to report for your company at this time Images can only be retrieved after the file(s) have actually been imaged (I.e.: The fax must either be In Queue or completed to be able to retrieve an image) This can be either an internal error, or if the status is a ‘Failed Conversion’, then there is no image to retrieve In the successful case, a binary response of the TIFF image (or PDF if the viewtype variable is set to pdf) of the transmitted fax is returned

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 15 of 35

DltransOperation Required POST Variables Variable username company password operation jobid

Description Assigned FAXAGE username Assigned FAXAGE company credential Assigned FAXAGE password Hard coded to ‘dltrans’ (w/o the quotes) The jobid to retrieve

Possible Responses Response ERR01: Database connection failed ERR02: Login incorrect

ERR06: No jobs to display or job id specified not found ERR24: File is not yet converted

ERR25: File does not exist



Meaning Internal FAXAGE error One or more of username, company, password is incorrect or your account is disabled for some reason The jobid you passed was not found or there are simply no jobs to report for your company at this time Images can only be retrieved after the file(s) have actually been imaged (I.e.: The fax must either be In Queue or completed to be able to retrieve an image) This can be either an internal error, or if the status is a ‘Failed Conversion’, then there is no image to retrieve In the successful case, a binary response of a PDF, which is a transmittal page is returned

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 16 of 35

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 username company password operation jobid

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

Optional POST Variables None

Possible Responses Response ERR01: Database connection failed ERR02: Login incorrect

ERR07: Job ID: not found, does not belong to you or is pending and cannot be cleared yet cleared ERR08: Unknown operation specified or bad POST

Meaning Internal FAXAGE error One or more of username, company, password is incorrect or your account is disabled for some reason The jobid you passed was not found, is not a job for your company or is in a pending state Successful clear of the specified jobid’s status record Either operation is not correctly hard coded or the POST was bad, the POST contents are returned for debugging purposes

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 17 of 35

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

Required POST Variables Variable username company password operation

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

Optional POST Variables Variable useronly

idasc

filename starttime

begin idgt

pagecount didnumber

Description 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 Hardcode to ‘1’. Causes faxes to be listed in order by recvid (see listfax record definition below) ascending. Recvid 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) Hardcode to ‘1’. Causes a fifth returned column, which contains the internal filename associated with each received fax 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 Set to a YYYY-MM-DD HH:MM:SS format string to list only faxes received after the specified date/time Set to a recvid in order to list faxes only greater than the passed recvid. Recvid is always unique and ascending, so sending the largest recvid you have seen so far ensures that you get only ‘new’ faxes that you have not yet listed If passed, will return the page count for each fax as the last item in the record. Set to a 10-digit DID on your account. If passed, only faxes incoming for the specified DID will be listed.

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 18 of 35

Possible Responses Response ERR01: Database connection failed ERR02: Login incorrect ERR11: No incoming faxes available

Meaning Internal FAXAGE error One or more of username, company, password is incorrect or your account is disabled for some reason There are no incoming faxes to list for you The format of the listfax record(s) returned is as follows (newline separation if multiple records). See below for definition of each field: (OPTIONAL: ) (OPTIONAL: )(OPTIONAL: )

ERR08: Unknown operation specified or bad POST

The ‘OPTIONAL’ return values above in parentheses have to do with whether the ‘filename’ and/or ‘starttime’ optional variables are passed. Either operation is not correctly hard coded or the POST was bad, the POST contents are returned for 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) pagecount – The number of pages in the fax

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 19 of 35

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 username company password operation faxid

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

Optional POST Variables None

Possible Responses Response ERR01: Database connection failed ERR02: Login incorrect ERR12: FAX ID not found or does not belong to you ERR13: File could not be opened

ERR08: Unknown operation specified or bad POST

Meaning Internal FAXAGE error One or more of username, company, password is incorrect or your account is disabled for some reason The faxid passed in is invalid or is an ID that does not belong to your company Internal FAXAGE error 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 Either operation is not correctly hard coded or the POST was bad, the POST contents are returned for debugging purposes

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 20 of 35

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

Required POST Variables Variable username company password operation faxid

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

Optional POST Variables None

Possible Responses Response ERR01: Database connection failed ERR02: Login incorrect ERR14: FAX ID not found or does not belong to you Deleted ERR08: Unknown operation specified or bad POST

Meaning Internal FAXAGE error One or more of username, company, password is incorrect or your account is disabled for some reason The requested faxid either does not exist or is not a fax belonging to your company Success condition Either operation is not correctly hard coded or the POST was bad, the POST contents are returned for debugging purposes

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 21 of 35

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 username company password operation jobid

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

Optional POST Variables None

Possible Responses Response ERR01: Database connection failed ERR02: Login incorrect ERR19: JOB ID not found or does not belong to you stopped ERR18: No jobid specified ERR20: Job ID - - is not In Queue ERR21: Job ID - - not found on fax server ERR22: Job ID - - is in transmission ERR23: Job ID - failed to stop ERR08: Unknown operation specified or bad POST

Meaning Internal FAXAGE error One or more of username, company, password is incorrect or your account is disabled for some reason The requested faxid either does not exist or is not a fax belonging to your company Success condition The ‘jobid’ variable was not specified or did not contain a numeric job id The jobid is not currently in an ‘In Queue’ or ‘Waiting for conversion’ status and, therefore, is ineligible to be stopped The jobid is not on the fax server at present and, therefore, cannot be stopped. This may be indicative of an internal status error within FAXAGE The jobid is currently being transmitted and, therefore, cannot be stopped General failure to stop. The request is otherwise valid, but just didn’t work Either operation is not correctly hard coded or the POST was bad, the POST contents are returned for debugging purposes

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 22 of 35

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 Username Company Password Operation didnumber

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

Optional POST Variables None

Possible Responses Response ERR01: Database connection failed ERR02: Login incorrect ERR17: DID not found or doesn't belong to you ERR16: invalid DID number Disabled ERR08: Unknown operation specified or bad POST

Meaning Internal FAXAGE error One or more of username, company, password is incorrect or your account is disabled for some reason The requested didnumber either does not exist or is not a number belonging to your company The value of the ‘didnumber’ variable is not a 10-digit number or was not specified Success condition Either operation is not correctly hard coded or the POST was bad, the POST contents are returned for debugging purposes

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 23 of 35

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 Username Company Password Operation didnumber

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

Optional POST Variables None

Possible Responses Response ERR01: Database connection failed ERR02: Login incorrect ERR17: DID not found or doesn't belong to you ERR16: invalid DID number Enabled ERR08: Unknown operation specified or bad POST

Meaning Internal FAXAGE error One or more of username, company, password is incorrect or your account is disabled for some reason The requested didnumber either does not exist or is not a number belonging to your company The value of the ‘didnumber’ variable is not a 10-digit number or was not specified Success condition Either operation is not correctly hard coded or the POST was bad, the POST contents are returned for debugging purposes

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 24 of 35

Portable Operation This allows for checking a number against FAXAGE’s rate center database to find out if it is portable to FAXAGE. What this actually checks is to see if the number is in a rate center we service.

Required POST Variables Variable Username Company Password Operation didnumber

Description Assigned FAXAGE username Assigned FAXAGE company credential Assigned FAXAGE password Hard coded to ‘portable’ (w/o the quotes) The 10-digit did to check

Optional POST Variables None

Possible Responses Response ERR01: Database connection failed ERR02: Login incorrect ‘0’ or ‘1’ ERR08: Unknown operation specified or bad POST

Meaning Internal FAXAGE error One or more of username, company, password is incorrect or your account is disabled for some reason Success condition – 1 indicates portable, 0 indicates not portable Either operation is not correctly hard coded or the POST was bad, the POST contents are returned for debugging purposes

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 25 of 35

Listlines Operation This allows for listing all lines currently assigned to your account.

Required POST Variables Variable Username Company Password Operation

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

Optional POST Variables None

Possible Responses Response ERR01: Database connection failed ERR02: Login incorrect List of lines ERR08: Unknown operation specified or bad POST

Meaning Internal FAXAGE error One or more of username, company, password is incorrect or your account is disabled for some reason Success condition – a newline-separated list of 10digit numbers assigned to your account is returned Either operation is not correctly hard coded or the POST was bad, the POST contents are returned for debugging purposes

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 26 of 35

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 Username Company Password

Value Assigned FAXAGE username Assigned FAXAGE company credential Assigned FAXAGE password

Optional POST variables NOTE: Although these parameters show as optional, one of the below two options *must* be specified (otherwise, nothing will be returned): • Both begin and end • ‘nuidgt’ (generally used in conjunction with ‘nuidshow’) Variable Name begin end nuidshow

nuidgt

didnumber

Value Timestamp in YYYY-MM-DD HH:MM:SS format from which records are to begin Timestamp in YYYY-MM-DD HH:MM:SS format from which records are to end 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 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 Set to a 10-digit DID on your account. If passed only incoming calls to the specified DID (as the dst field) will be returned.

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 27 of 35

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. Note, this is the raw billable duration and is not rounded to 6 second increments In either case, records are ascending-sorted by calldate.

Possible error responses for the getcdr.php URL Response ERR01: database connection failed ERR02: login incorrect

Meaning Internal FAXAGE error One or more of username, company or password is invalid or the account is currently locked out

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 28 of 35

The provision.php URL The 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 provision.php functionality works by sending an HTTPS POST to https://www.faxage.com/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 Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 29 of 35

Possible error responses for the provision.php URL These responses apply to all possible operations. Operation specific error responses and success cases are documented under each operation separately. Response ERR01: database connection failed ERR02: login incorrect

ERR03: unknown operation

Meaning Internal FAXAGE error One or more of username, company or password is invalid or the account is currently locked out The ‘operation’ variable is not specified or does have one of the valid operations as its value

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 30 of 35

The listac operation This operation lists available area codes for provisioning.

Required POST variables Variable Name username company password operation

Value Assigned FAXAGE username Assigned FAXAGE company credential Assigned FAXAGE password 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 Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 31 of 35

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

Required POST variables Variable Name username company password operation

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

Optional POST variables Variable Name ac

Value 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: 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: 303991DenverCO

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 32 of 35

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

Required POST variables Variable Name username company password operation

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

Optional POST variables Variable Name ac

npanxx

Value 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) 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 Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 33 of 35

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

Required POST variables Variable Name username company password operation didnumber

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

Optional POST variables None

Possible Return Values Return Value ERR04: Invalid DID number, ERR05: does not appear to be available provisioned

Meaning The ‘didnumber’ variable was not set to a 10-digit number Either you have specified a DID that doesn’t exist or it is already assigned to someone and is not available for provisioning This is the successful response case

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 34 of 35

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

Required POST variables Variable Name username company password operation didnumber

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

Optional POST variables None

Possible Return Values Return Value ERR04: Invalid DID number, ERR05: is invalid or does not belong to you deprovisioned

Meaning The ‘didnumber’ variable was not set to a 10-digit number The ‘didnumber’ either doesn’t exist or is not currently assigned to your account This is the successful response case

EC Data Systems Confidential and Proprietary - Patent information available at http://www.faxage.com/patent_notice.php Page 35 of 35