Fax Callbacks
Fax Callbacks are used as an alternative to the ReceiveInboundFax and ReceiveOutboundFax service methods, so that we will alert you when faxes are received or have completed sending, rather than you polling us for the data.
You will start out by configuring the settings in the web portal (Found under Settings>Manage account>Basic settings). You will need to be a user who has api permissions (granted by our support team) to see this feature so if you have additional users who will need to set/manage this feature you’ll need to ask us to give them permission as well.
Once configured, you will receive fax callbacks for all faxes processed inbound and outbound for your account.
After you select Fax callback settings, you will begin by enabling the Callback Service
Next, you will choose a "Master API user" from one of the API users in your organization (meaning a user who you have generated API credentials for). When we make the callback to your URL, we will pass an encrypted token along with the call based on this user's credentials, so that you can decrypt and verify that the call is valid and coming from us. This will also be the user who is notified when/if a Callback fails.
Now you need to tell us where to send the callbacks. You will specify for both inbound faxes and outbound faxes that have completed. You can use the same URL for both.
Then you will configure the Fax callback attempt/interval Settings. Here, for example, we will make 5 attempts to send this callback. If your server rejects our call, we will wait 2 minutes between each attempt, and then after 20 failed attempts we will suspend the Fax Callbacks. When Fax Callbacks are suspended, we will notify the email address entered here, and we will hold any pending calls in a queue until the Callbacks are enabled again.
NOTE: Fax callbacks will time out after 15 seconds.
The Log button allows you to run reports for the Fax callbacks for the API user on the account.
After you click the Log, you are given option to enter Report type, Start Date and End Date and then click Submit
Which in turn will generate the following report.
NOTE: We send the callback as an HTTP GET. Not a POST.
Here's a sample Fax Callback for an inbound fax. Notice that the key value pairs are the same for both callbacks, so values will be blank if they are not related to either inbound or outbound faxes. For instance, outfromfaxnumber does not apply to inbound faxing, and so it is blank.
&apikey=5787A4E0BCDE46F986D2E067AC70979C
&faxtype=1
&faxid=2150102030405000000
&faxsuccess=1
&faxpages=1
&faxdateiso=2015-03-06T23%3a59%3a04Z
&faxpwatermarkid=2150102030405999999
&hasbarcodedata=
&intofaxnumber=1-5555551212
&infromfaxnumber=1-5555551212
&infromcpn=15555551212
&infromcsid=Test+CSID
&outtofaxnumber=
&outfromfaxnumber=
&outfromcpn=
&outfromcsid=
&outsendfaxqueueid=
&outsendfaxtrackingcode=
&outresultcode=
&outerrorcode=
&outresultshortdescr=
&outresultdescr=
&outfaxattempts=
&istest=1
Here's one for an outbound fax:
&apikey=5787A4E0BCDE46F986D2E067AC70979C
&faxtype=0
&faxid=2150102030405000000
&faxsuccess=1
&faxpages=1
&faxdateiso=2015-03-07T00%3a00%3a10Z
&faxpwatermarkid=2150102030405999999
&intofaxnumber=
&infromfaxnumber=
&infromcpn=
&infromcsid=
&outtofaxnumber=1-5555551212
&outfromfaxnumber=1-5555551212
&outfromcpn=15555551212
&outfromcsid=Test+CSID
&outsendfaxqueueid=CEBC27A1AFB049D983B3660F698DB34D
&outsendfaxtrackingcode=Tracking+Code
&outresultcode=0
&outerrorcode=0
&outresultshortdescr=OK
&outresultdescr=OK
&outfaxattempts=1
&istest=1
Callback Parameters | Data Type | Description | Applies to In/Out faxes | Valid or example values |
Token | Varchar | Encrypted fax callback token | Both | Matches the same Sfax AESCrypto used for SendFax API calls |
apikey | Varchar(32) | API Key of Master API User for this account | Both | e.g., 5787A4EDBCDE46F9D6D2E067AC7097DC |
faxtype | Number(1) | Fax Type | Both | 0=Outbound fax 1=Inbound fax |
faxid | Number(19) | Fax Id | Both | 19 digit unique id e.g., 2150102030405000000 |
faxsuccess | Number(1) | Fax Success Flag | Both | 0=Failed 1=Succeeded |
faxpages | Number(5) | Fax Pages | Both | |
faxdateiso | UTC Date | Fax Date Time in ISO format | Both | e.g., 2015-03-06T23:59:04Z |
faxpwatermarkid | Number(19) | Fax Watermark | Both | e.g., 2150102030405999999 |
hasbarcodedata | Number(1) | Barcode included in document | Both | 0=false 1=true |
intofaxnumber | Varchar(25) | In To Fax Number | Inbound | e.g., 1-5555551212 |
infromfaxnumber | Varchar(25) | In From Fax Number | Inbound | e.g., 1-5555551212 |
infromcpn | Varchar(25) | In From Fax CPN | Inbound | e.g., 5555551212 |
infromcsid | Varchar(25) | In From Fax CSID | Inbound | e.g., Test CSID |
outtofaxnumber | Varchar(25) | Out To Fax Number | Outbound | e.g., 1-5555551212 |
outfromfaxnumber | Varchar(25) | Out From Fax Number | Outbound | e.g., 1-5555551212 |
outfromcpn | Varchar(25) | Out From Fax CPN | Outbound | e.g., 5555551212 |
outfromcsid | Varchar(25) | Out From Fax CSID | Outbound | e.g., Test CSID |
outsendfaxqueueid | Varchar(100) | Out Send Fax Queue Id | Outbound | If sent from the SendFax API |
outsendfaxtrackingcode | Varchar(40) | Out Send Fax Tracking Code | Outbound | If send from the SendFax API with Tracking Code |
outresultcode | Varchar(8) | Out Result Code | Outbound | See http://sfax.scrypt.com/article/358-error-codes-and-definitions |
outerrorcode | Varchar(8) | Out Error Code | Outbound | See http://sfax.scrypt.com/article/358-error-codes-and-definitions |
outresultshortdescr | Varchar(100) | Out Result Short Description | Outbound | |
outresultdescr | Varchar(100) | Out Result Long Description | Outbound | |
outfaxattempts | Number(5) | Number of Sending Attempts | Outbound | |
istest | Number(1) | Is Test | Both | 0=Live callback 1=Test callback |