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.

https://testapi.sfaxme.com/api/testfaxcallback?token=0HiECdCWsySyY%2fEVE1%2bmzfZLTw6TtKLtd%2bn3Y3ipy0fKt7gGRREb1z%2bGvXFe%2bBTbxWj4DWoafF%2bJvHmaFDGOajdDhcZ%2fvlr8XcVdkRBuwAfWvITsx93eRUqEDsUYVu%2bC

&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:

https://testapi.sfaxme.com/api/testfaxcallback?token=0HiECdCWsySyY%2fEVE1%2bmzfZLTw6TtKLtd%2bn3Y3ipy0fKt7gGRREb1z%2bGvXFe%2bBTbxWj4DWoafF%2bJvHmaFDGOauyJGAhgJxtNOKGUvqY5Ljp5bUcD1Jh2sNxS9N%2fbaCbo

&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