Service Methods

All Service Methods are invoked in a consistent manner using a simple HTTPS get or post invocation as described below:

  • A single common HTTPS endpoint is used for all Service Method invocations: /api/ 
  • The name of the Service Method is appended to the base URL
  • Advanced authorization using an Api Key and AES Token
  • Internet Protocol HTTPS (required) api.sfaxme.com Web server DNS name.
  • Required parameters are listed in bold font

ReceiveInboundFax

Fax information will be returned for all fax lines assigned to the api user since your last call.  You will be able to parse out by fax number. You can then use the FaxID's returned in the response to Download the fax as Pdf or Tif.

Note:  With every call you will receive the next 500 faxes that have completed since your last call.  We are tracking the Watermark Id for you and you do not need to do anything more.  If there are more than 500 faxes you see that HasMoreItems is true, in which case you will need to continue to make the call until HasMoreItems is false.

Alternatively, you can configure  Fax Callbacks which will notify you when an inbound fax is received.

Parameters Description
?token Generated using AES encryption. Sfax provides a class that is included (See sample AESCrypto). The token is a combination of the Username, ApiKey, EncryptionKey and InitVector (supplied). The token is only valid for 15 minutes.  We recommend generating a new token with each call, as shown in our sample code.
&ApiKey Supplied by Sfax and is a parameter used to connect to the api and is also used a parameter for the AES token
&WatermarkId Used in a specific instance where you would like to revert back to a specific watermark id and start receiving faxes again from that point.
&StartDateUTC
&EndDateUTC 		Used in specific instances where you need to recover previously received faxes.  The Date format is in UTC and is in the following format (YYYY-MM-DD Thh:mm:ssZ).  You will then need to adjust your date range to get the next set.
&MaxItems Parameter is a numeric number from 1 to 500. If no number is passed the system defaults to 500.

DownloadInboundFaxAsPdf

Parameters Description
?token Generated using AES encryption. Sfax provides a class that is included (See sample AESCrypto). The token is a combination of the Username, ApiKey, EncryptionKey and InitVector (supplied). The token is only valid for 15 minutes.  We recommend generating a new token with each call, as shown in our sample code.
&ApiKey Parameter supplied by Sfax and is a parameter used to connect to the api and is also used a parameter for the AES token.
&FaxId Parameter is the FaxId provided by the response data returned by the ReceiveInboundFax method call.

DownloadInboundFaxAsTif

Parameters  Description
?token Generated using AES encryption. Sfax provides a class that is included (See sample AESCrypto). The token is a combination of the Username, ApiKey, EncryptionKey and InitVector (supplied).  The token is only valid for 15 minutes.  We recommend generating a new token with each call, as shown in our sample code.
&ApiKey Parameter supplied by Sfax and is a parameter used to connect to the api and is also used a parameter for the AES token.
&FaxId Parameter is the FaxId provided by the response data returned by the ReceiveInboundFax method call.

SendFax

URL Construct:

https://api.sfaxme.com/api/";methodSignature = "SendFax" ?token = (AES Encrypted using Username,ApiKey,EncryptionKey,EncryptionInitVector) &ApiKey= "" &RecipientName = "" &RecipientFax = "1XXXXXXXXXX" &OptionalParams=   Example ("&OptionalParams=" + "CoverPageName=", HttpUtility.UrlEncode(coverpage1) + ";" + "CoverPageSubject=", HttpUtility.UrlEncode(subject) + ";" + "CoverPageReference=", HttpUtility.UrlEncode(reference) + ";" + "TrackingCode=", HttpUtility.UrlEncode(trackingid) )

Sample encoded URL:

https://api.sfaxme.com/api/SendFax?token=5c802wxZLX7LuFu2xbvRCcP1r87TX5P6IpErNPpr2VpGr8QpW5jkZWiE32of%2fKO5ExwJMOf2K6KP%2bGeGkn4DX8F0EgmsZE0CxSXpgxckPOX4dRDd1IPCecBLxVNkw9Yb&apikey=D911F4D4C2B94E00B04C8F3A2AE6E417&RecipientName=Test&RecipientFax=15123668506&OptionalParams=CoverPageName=Default;CoverPageSubject=Test;CoverPageReference=Test1234;TrackingCode=1234&" "=""
Parameters Description
?token Generated using AES encryption. Sfax provides a class that is included (See sample AESCrypto). The token is a combination of the Username, ApiKey, EncryptionKey and InitVector (supplied). The token is only valid for 15 minutes. We recommend generating a new token with each call, as shown in our sample code.
&ApiKey Parameter supplied by Sfax and is a parameter used to connect to the api and is also used a parameter for the AES token.
&RecipientName Parameter pertains to the name of the recipient receiving the fax.
&RecipientFax Parameter pertains to the fully qualified fax number to send to. (ie. 15123345678. Do NOT use dashes or other characters)
&BarcodeOption Parameter is used only to pass information to create a barcode on fax pages outgoing.

BarcodeData= is a string value used to create the barcode data, additional barcodes can be passed using the same parameter BarcodeData in a separate BarcodeOption set.
BarcodeX=
BarcodeY= These are both integer values to determine the x and y coordinate position on a page to place the barcode(s). A 8.5 X 11 page is 1700 X 2200 pixels. *We recommend placing the barcode 50 pixels or more from the edge of the page.
BarcodePage= is an integer value used to determine what page(s) to place the barcode(s) on.
BarcodeScale= is preset to size 3 but can be passed as an additional parameter to change the sizing of the barcode. The sizes available are 3,4,5,6,7,8,9,20,30 and 40.

Example:
&BarcodeOption=BarcodeData=12345;BarcodeX=1;BarcodeY=1;BarcodePage=1;
BarcodeScale=3

We only write DataMatrix barcodes. We can read DataMatrix and PDF417.
We can read and write alphanumeric. Extended ASCII characters may be stripped from the data or not allowed, but specific cases would need to be looked at if encountered.

For more information, including a use case please  Click here
&OptionalParams
 		Used to pass information into the cover page fields, and/or to override system defaults for other functions noted below. *All parameters are URL encoded.
*Separate each parameter with semicolons (;) *Do not pass a semicolon (;) with any of the values as we will see this as a break between parameters. Also avoid using <>. If you notice any other problems with special characters please send us examples.

Cover Pages

CoverPageName (200 characters maximum): Pass this to select your cover page. We have 3 system cover pages.
If you want to upload a custom cover page you can send that to us via a support ticket and we’ll upload to your account. If you want to set a cover page as your default cover page, you can log into the web portal, go to settings, and then select the default cover page for the api user. You can then pass Default as the cover page name. Otherwise you can pass the full name of the Cover Page or None if you don’t want to use a cover page. CoverPageSubject (200 characters maximum): Will populate into the Subject field.
CoverPageReference (200 characters maximum): Will populate into the Reference field.
CoverPageRemarks (1000 characters maximum): Will populate into the Remarks field.
CoverPageFromName (200 character maximum): Will populate into the From field.
CoverPageFromPhone:(50 character maximum): Will populate into the Phone field.
CoverPageTimeZone: This will set the time that appears in the Time field.

Valid TimeZone parameters:
ALASKAN STANDARD TIME
PACIFIC STANDARD TIME
MOUNTAIN STANDARD TIME
US MOUNTAIN STANDARD TIME
CENTRAL STANDARD TIME
EASTERN STANDARD TIME
ATLANTIC STANDARD TIME
WEST PACIFIC STANDARD TIME

Example usage:
&OptionalParams=CoverPageName=Default;CoverPageSubject=xx;
CoverPageReference=xx;CoverPageFromName=Test Name;
CoverPageFromPhone=(512)555-1234; CoverPageTimeZone=PACIFIC STANDARD TIME 

Other

  • TrackingCode (alphanumeric) (100 characters maximum): Use this to pass any identifying information you want to use to track your fax request and it will be returned to you in the ReceiveOutboundFax response when the fax request has completed.
  • MaxAttempts: A number between 1 and 6 (total number of attempts to send fax).
  • AttemptInterval: A number between 60 and 360 (seconds between retries).
  • SenderFaxNumber: This will allow you to override the default outbound fax number and send out the fax from any fax number that the api user is assigned to. Include country code plus fax number with no dashes. (ex. 18887774545) If this parameter is not included, faxes will go out from the default fax number for the API user.
  • priority: This value indicates the priority of a given fax transmission. priority=0 is low priority, while priority=1 is normal priority. For example: &OptionalParams=CoverPageName=Default;CoverPageSubject=Test;CoverPageReference=Test1234;TrackingCode=1234;priority=0 would result in a fax using the default cover page, with the subject line "Test," a cover page reference set to "Test1234" and a tracking code of "1234." The priority set to 0 indicates a low priority.

SendFaxStatus

This method allows you to get the status for individual faxes sent via the SendFax API method.

End point: https://api.sfaxme.com/api/SendFaxStatus
Parameters Description
Token Generated using AES encryption. Sfax provides a class that is included (See sample AESCrypto). The token is a combination of the Username, ApiKey, EncryptionKey and InitVector (supplied). The token is only valid for 15 minutes. We recommend generating a new token with each call, as shown in our sample code.
Apikey Parameter supplied by Sfax, used to connect to the API and as a parameter for the AES token.
SendFaxQueueId The SendFaxQueueId that is returned when a fax is sent via the SendFax API method.
Response Example: 
<SendFaxStatusReponse 
xmlns:xsi="<a href="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/<wbr>2001/XMLSchema-instance</a>" 
xmlns:xsd="<a href="http://www.w3.org/2001/XMLSchema">http://www.w3.org/<wbr>2001/XMLSchema</a>"> 
    <isSuccess>true</isSuccess> 
    <message>Fax request is complete</message> 
    <RecipientFaxStatusItems> 
       <RecipientFaxStatus> 
          <SendFaxQueueId>414B2A56BE7F419585890F2967BE91<wbr>D0</SendFaxQueueId> 
	  <IsSuccess>true</IsSuccess> 
          <ResultCode>0</ResultCode> 
          <ErrorCode>0</ErrorCode> 
          <ResultMessage>OK</<wbr>ResultMessage> 
          <RecipientName>MikeBarcode</<wbr>RecipientName> 
          <RecipientFax>1-8882323562</<wbr>RecipientFax> 
          <TrackingCode /> 
          <FaxDateUtc>2015-11-12T19:25:<wbr>13Z</FaxDateUtc> 
          <FaxId>2151112192512997504</<wbr>FaxId> 
          <Pages>1</Pages> 
          <Attempts>1</Attempts> 
          <SenderFax>1-8882323562</<wbr>SenderFax> 
          <BarcodeItems> 
             <BarcodeItem> 
                <BarcodeSpacingXAxis>0</<wbr>BarcodeSpacingXAxis> 
                <BarcodeSpacingYAxis>0</<wbr>BarcodeSpacingYAxis> 
                <BarcodeType>1</BarcodeType> 
                <BarcodeMode>1</BarcodeMode> 
                <BarcodeData>D9dd5b39d-71e0-<wbr>4009-9a40-323374e4564</<wbr>BarcodeData> 
                <BarcodeX>10</BarcodeX> 
                <BarcodeY>10</BarcodeY> 
                <BarcodePage>1</BarcodePage> 
                <BarcodeScale>50</<wbr>BarcodeScale> 
                <BarcodeWidth>0</<wbr>BarcodeWidth> 
                <BarcodeHeight>0</<wbr>BarcodeHeight> 
             </BarcodeItem> 
          </BarcodeItems> 
          <FaxSuccess>1</FaxSuccess> 
          <OutboundFaxId><wbr>2151112192512997504</<wbr>OutboundFaxId> 
	  <FaxPages>1</FaxPages> 
          <FaxDateIso>2015-11-12T19:25:<wbr>13Z</FaxDateIso> 
          <WatermarkId><wbr>2151112192630997061</<wbr>WatermarkId> 
      </RecipientFaxStatus> 
   </RecipientFaxStatusItems> 
</SendFaxStatusReponse>

SendFaxFromURL

Parameters Description
?token See SendFax
&ApiKey See  SendFax

&RecipientName

See  SendFax
&RecipientFax See  SendFax
&FileType FileType: parameter is used to tell the system what type of files are in the Cloud stream process and which Sfax Renderer to use. Can only send the same file types per request. Required on every transaction.
&FileDataURL FileDataURL: parameter is used to tell the system where to get the files to send and process. Required on every transaction.
&BarcodeOption See  SendFax.
&OptionalParams See  SendFax.

ReceiveOutboundFax  

Used to receive information for all faxes that have completed since the last call.   If the fax is not returned here, it is assumed that it is still processing.

Alternatively, you can configure Fax Callbacks which will notify you when faxes have completed

Note:  With every call you will receive the next 500 faxes that have completed since your last call.  We are tracking the watermark ID for you and you do not need to do anything more.  If there are more than 500 faxes you see that HasMoreItems is true, in which case you will need to continue to make the call until HasMoreItems is false.

Parameters Description
?token Generated using AES encryption. Sfax provides a class that is included (See sample AESCrypto). The token is a combination of the Username, ApiKey, EncryptionKey and InitVector (supplied). The token is only valid for 15 minutes.  We recommend generating a new token with each call, as shown in our sample code.
&ApiKey Supplied by Sfax and is a parameter used to connect to the api and is also used a parameter for the AES token.

&StartDateUTC
&EndDateUTC

Used in specific instances where you need to recover previously received faxes.  The Date format is in UTC and is in the following format (YYYY-MM-DD Thh:mm:ssZ).  You will then need to adjust your date range to get the next set.
&WatermarkId Used in a specific instance where you would like to revert back to a specific watermark id and start receiving faxes again from that point.
&MaxItems You will pass a number from 1 to 500 to let us know how many faxes you would like returned in the response. If no number is passed the system defaults to 500.   


DownloadOutboundFaxAsPdf

Parameters Description
?token Generated using AES encryption. Sfax provides a class that is included (See sample AESCrypto). The token is a combination of the Username, ApiKey, EncryptionKey and InitVector (supplied).  The token is only valid for 15 minutes.  We recommend generating a new token with each call, as shown in our sample code.
&ApiKey Supplied by Sfax and is a parameter used to connect to the api and is also used a parameter for the AES token.

&FaxId

Parameter is the FaxId provided by the xml response data returned by the ReceiveOutboundFax method call.

DownloadOutboundFaxAsTif

Parameters  Description
?token Generated using AES encryption. Sfax provides a class that is included (See sample AESCrypto). The token is a combination of the Username, ApiKey, EncryptionKey and InitVector (supplied). The token is only valid for 15 minutes.  We recommend generating a new token with each call, as shown in our sample code.
&ApiKey Supplied by Sfax and is a parameter used to connect to the api and is also used a parameter for the AES token.
&FaxId Parameter is the FaxId provided by the xml response data returned by the ReceiveOutboundFax method call.
All files streamed up for faxing must include a file extension to be processed by the API renders or the fax file will not process properly.

UsageReport (Beta)

Service methods and code samples