Sales
Click for numbers
Welcome User Tools Developer Tools Prices Help Sign up Login
You are here: Home > Developer Tools > Fax Web Service > Outbound Method Reference

Interfax Outbound Fax Web Service Reference

Sections

Overview
Requirements
Programmer's Guide
Method Reference
     Sendfax
     SendfaxEx (superseded by SendfaxEx_2)
     SendfaxEx_2
     SendCharFax
     FaxStatus
     FaxStatusEx
     FaxQuery (preferred method for querying status)
     GetFaxImage
     FaxStatusXML
     ReSendFax
     HideFax
Appendix A - Error Codes
Appendix B - Special Formats
     Fax Number - Input
     Fax Number - Output
     FileData
     XML Status Data

1. Overview

The Interfax Fax Web Service is a commercial subscription-based service which enables transmission and reception of fax messages without the need to install any hardware or software. The original document to be transmitted may be of various formats, such as HTML, Microsoft Word, PDF etc. Received faxes are in TIF format.

As an extension to to sending capabilities, the Interfax Fax Web Service provides facilities for retrieving status information regarding fax messages sent through it.

It supports both secure and non-secure communication between the custom-programmed application and the Interfax server.

Click here to jump to a side-by-side comparison of the Web Service transmission methods.

For advanced uses, the optional Interfax Admin Web Service allows user preference management and addition or removal of users and services.

2. Requirements

Access to the Internet over port 80 or 443.

Support for XML Web Services. Such support is available through a wide range of tools, such as:

  • Microsoft .NET languages (VB.net, C#, ASPX)
  • Java
  • SOAP toolkits
  • etc.

3. Programmer's guide

3.1 Accessing the Fax Web Service

3.1.1 The outbound fax Web Service WSDL may be accessed at http://ws.interfax.net/dfs.asmx?WSDL or securely at https://ws.interfax.net/dfs.asmx?WSDL.

3.2 Sending a quick fax

The simplest way to send a fax is by using the "Sendfax" method for binary files (MS Word .DOC, MS Excel .XLS, etc) or the "SendCharFax" method for textual files (such as simple ASCII). These require minimal data and enable a quick submission of a single document to a single destination fax number.

Upon successful submission of a message to the Interfax Web Service, Sendfax and SendCharFax return a token value that can later be used to query the fax's status. This token is called TransactionID.

In case of an error in submitting the message to the service, an error code is returned.

3.3 Sending a fax with advanced features

If you require more flexibility in sending a fax, you may want to use the SendfaxEx_2 method.

This method requires more parameters, but enables more advanced sending capabilities, such as:

  • Sending multiple documents
  • Sending a fax to multiple destinations
  • Scheduling the transmission time of a fax
  • Controlling the CSID and Reply email address
  • Providing a reference (Subject field) to be used when obtaining message status

Upon successful submission of the message to the Interfax Web Service, SendfaxEx_2 returns a token value that can later be used to query the fax's status.

In case of an error in submitting the message to the service, an error code is returned.

3.4 Getting outbound status

If you wish to programmatically retrieve the status of a previously submitted message, you can use the FaxStatus or FaxStatusEx  methods.

FaxStatus and FaxStatusEx return status information for either one or multiple messages in a single call.

3.5 Retrieving the outbound fax image

The image of a fax can be obtained by calling the GetFaxImage method. The GetFaxImage request is submitted with a TransactionID and in return downloads a multi-page fax image in TIFF format. The image can be stored as a file on a disk, viewed or printed by standard fax viewers, such as Imaging for Windows.  

3.6 Getting XML-formatted outbound status

Certain application will find it easier to receive the status data as an XML-formatted buffer. The FaxStatusXML method works in the same manner as FaxStatus. The only difference is the format of the status data returned by the method.

4. Method reference

4.1 Method name: Sendfax

Parameters:

Name Type Comments
Username String As provided during registration
Password String As provided during registration
FaxNumber String The destination fax number in standard international notation e.g. +44-207-3456789 (see Appendix B)
FileData base64Binary Binary data of the document (see Appendix B)
FileType String e.g. DOC, HTML, PDF, etc.

Return value: Long. In case of successful submission - the value contains the TransactionID. In case of a failure, a negative value is returned.

List of return codes is shown on Appendix A.

4.2 Method name: SendfaxEx

Please note that this method is retained for backward-compatibility only. We encourage new development to use the SendfaxEx_2 method.

Parameters:

Name Type Comments
Username String As provided during registration
Password String As provided during registration
FaxNumbers String A single fax number or a list of semicolon-separated fax numbers, e.g: 1-212-3456789;+44161-999 8888;01132-45 45 45 45. Maximum number of fax numbers: 500.

If multiple fax numbers are provided, multiple transactions with consecutive TransactionID's will be created. All such transactions will share a single ParentTransactionID, whose value is the TransactionID of the FIRST transaction in the batch.
FilesData base64Binary Binary data of the document(s). If two or more documents are uploaded, concatenate their binary data.

The total length of this parameter is the sum of all items in the FileSizes parameter.

If an uploaded file's size is greater than 250KB, or if experiencing timeouts, consider using the Chunk Data Upload methods. If referencing a file uploaded by these methods (using its SessionID in parameter FileSizes below), this parameter is ignored. Send a zero-size buffer.
FileTypes String List of FileType, separated by ;s, e.g: DOC;HTML;HTML.

Number of items in the list should match number of documents, even if all documents are of the same type.
FileSizes String List of numbers, separated by ;s, each defining the length of a document

Example: 12034;8888;18478

If the file(s) were uploaded with the Chunk Data Upload method, add the string /sessionID=[session ID]. The SessionID is the one returned by the StartFileUpload call. Example: 12034;8888;18478/sessionID=123456

Postpone DateTime Time to schedule the transmission. In case no scheduling is required (i.e. ASAP), use any date in the past, like '2000-01-01'.
IsHighResolution Boolean True ==> Fine, False ==> Standard. True renders documents more finely but takes longer to transmit (may therefore be more costly).
CSID String Sender CSID (up to 20 characters). If not provided, user's default CSID is used.
Subject String Up to 60 characters, to be used as a reference only. The Subject parameter can be obtained by status query, but is not included in the transmitted fax message.
ReplyAddress String An optional e-mail address to which feedback messages will be sent. If not provided, user's default reply address is used.


Return value: Long. In case of successful submission - the value contains a Transaction ID. In case of a failure, a negative value is returned. List of return codes is shown on Appendix A.

4.3 Method name: SendfaxEx_2

Parameters:

Name Type Comments
Username String As provided during registration
Password String As provided during registration
FaxNumbers String A single fax number or a list of semicolon-separated fax numbers, e.g: 1-212-3456789;+44161-999 8888;01132-45 45 45 45. Maximum number of fax numbers: 500.

If multiple fax numbers are provided, multiple transactions with consecutive TransactionID's will be created. All such transactions will share a single ParentTransactionID, whose value is the TransactionID of the FIRST transaction in the batch.
Contacts String Comma-delimited list of names. The entered string will appear: (1) for reference in the outbound queue, and (2) in the outbound fax header. When faxing to a list managed online through your account, this field will be populated by the "Person Name" field in the list, or if unavailable, by the "Company Name" field in the list. Individual recipients and lists may be mixed.
FilesData base64Binary Binary data of the document(s). If two or more documents are uploaded, concatenate their binary data.

The total length of this parameter is the sum of all items in the FileSizes parameter.

If an uploaded file's size is greater than 250KB, or if experiencing timeouts, consider using the Chunk Data Upload methods. If referencing a file uploaded by these methods (using its SessionID in parameter FileSizes below), this parameter is ignored. Send a zero-size buffer.
FileTypes String List of FileType, separated by ;s, e.g: DOC;HTML;HTML.

Number of items in the list should match number of documents, even if all documents are of the same type.
FileSizes String List of numbers, separated by ;s, each defining the length of a document

Example: 12034;8888;18478

If the file(s) were uploaded with the Chunk Data Upload method, add the string /sessionID=[session ID]. The SessionID is the one returned by the StartFileUpload call. Example: 12034;8888;18478/sessionID=123456
Postpone DateTime Time to schedule the transmission. In case no scheduling is required (i.e. ASAP), use any date in the past, like '2001-01-00'.
RetriesToPerform Integer Number of transmission attempts to perform, in case of fax transmission failure. The minimum interval between two subsequent attempts is set through your account defaults.
CSID String Sender CSID (up to 20 characters). If not provided, user's default CSID is used.
PageHeader String The fax header text to insert at the top of the page. Enter a string template to send a fax with a dynamically-populated header. For placeholder documentation, see your online settings under Preferences -> Outgoing -> Header Properties. For example, in the string To: {To} From: {From} Pages: {TotalPages} the placeholders {To}, {From}, and {Pages} will be populated by their respective values.

Alternatively, enter Y or a null string to send the fax with a constant header that is defined in your online preferences above or N to send the fax without a header.
JobID String Reserved for future use
Subject String Up to 60 characters, to be used as a reference only. The Subject parameter can be obtained by status query, but is not included in the transmitted fax message.
ReplyAddress String An optional e-mail address to which feedback messages will be sent. If not provided, user's default reply address is used.
PageSize String A4, Letter, Legal, or B4. If not provided, user's default page size is used. Add -fit to fit (enlarge or reduce) to a certain page size, e.g. A4-fit.
PageOrientation String Portrait or Landscape. If not provided, user's default page orientation is used.
IsHighResolution Boolean True ==> Fine, False ==> Standard. True renders documents more finely but takes longer to transmit (may therefore be more costly).
IsFineRendering Boolean True ==> Optimize for greyscale, False ==> Optimize for B&W. "False" is recommended for textual, black & white documents, while "True" is better for gray scale text and for images.


Return value: Long. In case of successful submission - the value contains a Transaction ID. In case of a failure, a negative value is returned. List of return codes is shown on Appendix A.

4.4 Method name: SendCharFax

Parameters:

Name Type Comments
Username String As provided during registration
Password String As provided during registration
FaxNumber String The destination fax number in standard international notation e.g. +44-207-3456789 (see Appendix B)
Data String Data of the document (text documents only)
FileType String e.g. DOC, HTML, PS, etc. Default is TXT

Return value: Long. In case of successful submission - the value contains the TransactionID. In case of a failure, a negative value is returned. List of return codes is shown on Appendix A.

4.5 Method name: FaxStatus

Parameters:

Name Type Comments
Username String As provided during registration
Password String As provided during registration
LastTransactionID Integer Only messages with TransactionID smaller than this parameter will be returned. For all transactions - use 99999999.

This feature enables to obtain the latest, most interesting, transactions in a very short time and display it. Afterwards, more data may be obtained concurrently with display of previous data.
MaxItems Integer Maximum number of FaxItem elements to be returned.
TotalCount Integer An output parameter - total number of transactions for this user (regardless of number of transactions returned).
ListSize Integer An output parameter - total number of transactions actually returned by the query (size of FaxItems array).
ResultCode Integer 0= OK; less than 0 = Error, see Appendix A

Return value:
FaxItems Array Array of FaxItem
FaxItem Definition
TransactionID Integer  
SubmitTime DateTime The time when the transaction was originally submitted by the client
PostponeTime DateTime Time to which transmission was scheduled the transmission. Returns '0000-00-00' if not postponed
CompletionTime DateTime End time of last of all transmission attempts
DestinationFax String The fax number in a canonical format (see Appendix B)
RemoteCSID String Receiving party CSID (up to 20 characters)
PagesSent Short Number of successfully sent pages
Status Integer Fax status. 0= OK; greater than 0 = Error (See Interfax Error Codes)
Duration Integer Transmission time in seconds
Subject String Original value as submitted
PagesSubmitted Short Number of pages originally submitted

4.6 Method name: FaxStatusEx

Parameters:

Name Type Comments
Username String As provided during registration
Password String As provided during registration
LastTransactionID Integer Only messages with TransactionID smaller than this parameter will be returned. For all transactions - use 99999999.

This feature enables to obtain the latest, most interesting, transactions in a very short time and display it. Afterwards, more data may be obtained concurrently with display of previous data.
MaxItems Integer Maximum number of FaxItem elements to be returned.
TotalCount Integer An output parameter - total number of transactions for this user (regardless of number of transactions returned).
ListSize Integer An output parameter - total number of transactions actually returned by the query (size of FaxItems array).
ResultCode Integer 0= OK; less than 0 = Error, see Appendix A

Return Value:
FaxItems Array Array of FaxItemEx
FaxItemEx Definition
ParentTransactionID Integer In case of a Broadcast - the ID of the 1st item
TransactionID Integer  
SubmitTime DateTime Time when the transaction was originally submitted by the client
PostponeTime DateTime Time to which transmission was scheduled the transmission. Returns '0000-00-00' if not postponed
CompletionTime DateTime End time of last of all transmission attempts
UserID String  
Contact String The text which was inserted into the Contacts property upon submission of the fax with method SendfaxEx_2.
JobID String Reserved for future use
DestinationFax String The fax number in a canonical format (see Appendix B)
ReplyEmail String The E-mail address to which a confirmation message is to be sent
RemoteCSID String Receiving party CSID (up to 20 characters).
PagesSent Short Number of successfully sent pages.
Status Integer Fax status. 0= OK; greater than 0 = Error (See Interfax Error Codes)
Duration Integer Transmission time in seconds.
Subject String Original value as submitted.
PagesSubmitted Short Number of pages originally submitted.
SenderCSID String CSID of calling party
Priority Short Reserved for future use
Units Decimal Number of units to be billed (pages or tenths of minutes)
CostPerUnit Decimal Monetary units, in account currency
PageSize String A4, Letter, Legal, or B4
PageOrientation String Portrait or Landscape
PageResolution String Standard or Fine
RenderingQuality String Standard (optimize for black & white) or Fine (optimize for greyscale)
PageHeader String Reserved for future use
RetriesToPerform Short Reserved for future use
TrialsPerformed Short Reserved for future use

4.7 Method name: FaxQuery

Parameters:

Name Type Comments
Username String As provided during registration
Password String As provided during registration
Verb String

PARENT <transactionid>; Retrieve ALL items in a batch
ACTIVE ; leave VerbData empty to retrieve ALL incomplete (active) items
GT <transactionid> transactions with id greater than the given transactionid
GE <transactionid> transactions with id greater than or equal to the given transactionid
LT <transactionid> transactions with id smaller than the given transactionid
LE <transactionid> transactions with id smaller than or equal to the given transactionid
EQ <transactionid> transactions with id equal to the given transactionid
BETWEEN <transactionid1,transactionid2> transactions with id greater than greater than or equal to transactionid1 and id smaller than or equal to transactionid2.
IN <transactionid1,transactionid2> transactions in list.

VerbData String Place <transactionid> required above here. See Verb.
MaxItems Integer Maximum number of FaxItem elements to be returned. Use -1 for no limit.
ResultCode Integer 0= OK; less than 0 = Error, see Appendix A

Return Value:
FaxItems Array Array of FaxItemEx
FaxItemEx Definition
ParentTransactionID Integer In case of a Broadcast - the ID of the 1st item
TransactionID Integer  
SubmitTime DateTime Time when the transaction was originally submitted by the client
PostponeTime DateTime Time to which transmission was scheduled the transmission. Returns '0000-00-00' if not postponed
CompletionTime DateTime End time of last of all transmission attempts
UserID String  
Contact String The text which was inserted into the Contacts property upon submission of the fax with method SendfaxEx_2.
JobID String Reserved for future use
DestinationFax String The fax number in a canonical format (see Appendix B)
ReplyEmail String The E-mail address to which a confirmation message is to be sent
RemoteCSID String Receiving party CSID (up to 20 characters).
PagesSent Short Number of successfully sent pages.
Status Integer Fax status. 0= OK; greater than 0 = Error (See Interfax Error Codes)
Duration Integer Transmission time in seconds.
Subject String Original value as submitted.
PagesSubmitted Short Number of pages originally submitted.
SenderCSID String CSID of calling party
Priority Short Reserved for future use
Units Decimal Number of units to be billed (pages or tenths of minutes)
CostPerUnit Decimal Monetary units, in account currency
PageSize String A4, Letter, Legal, or B4
PageOrientation String Portrait or Landscape
PageResolution String Standard or Fine
RenderingQuality String Standard (optimize for black & white) or Fine (optimize for greyscale)
PageHeader String Reserved for future use
RetriesToPerform Short Reserved for future use
TrialsPerformed Short Reserved for future use

4.8 Method name: GetFaxImage

Parameters:

Name Type Comments
Username String As provided during registration
Password String As provided during registration
TransactionID Integer  
Image base64Binary Output parameter: Binary data of the TIFF image.

Return value: Long. If retrieval of fax image is successful, return value is 0. In case of failure, a negative value is returned.

List of return codes is shown on Appendix A.


4.9 Method name: FaxStatusXML

Parameters:

Name Type Comments
Username String As provided during registration
Password String As provided during registration
LastTransactionID Integer Only messages with TransactionID smaller than this parameter will be returned. For all transactions - use 99999999.

This feature enables to obtain the latest, most interesting, transactions in a very short time and display it. Afterwards, more data may be obtained concurrently with display of previous data.
MaxItems Integer Maximum number of FaxItem elements to be returned.
TotalCount Integer An output parameter - total number of transactions for this user (regardless of number of transactions returned).
ListSize Integer An output parameter - total number of transactions actually returned by the query (size of FaxItems array).
FaxStatusXMLResult String A buffer containing the status information in XML format. See Appendix B for detailed description.


Return value: Integer

0 - OK
< 0 - Error, see Appendix A

4.10 Method name: ReSendFax

Parameters:

Name Type Comments
Username String As provided during registration
Password String As provided during registration
TransactionID Integer TransactionID of fax to be resent.
FaxNumber String The destination fax number to which to resend this transaction, in standard international notation e.g. +44-207-3456789 (see Appendix B)

Return value: Long. In case of successful submission - the value contains the TransactionID. In case of a failure, a negative value is returned.

List of return codes is shown on Appendix A.


4.11 Method name: HideFax

Parameters:

Name Type Comments
Username String As provided during registration
Password String As provided during registration
TransactionID Integer TransactionID of transaction to hide from outbound queue.

Return value: Long. If hiding of transaction is successful, return value is 0. In case of failure, a negative value is returned.

List of return codes is shown on Appendix A.

Appendix A - Return codes

Results of Web Service transaction

Please note: The result codes indicate the success/failure of transacting with the Web Service. They do NOT relate to success/failure of a fax transmission. For completeness, inbound fax method return codes are included in the table.

Value Description
(any value greater than 0) TransactionID. This indicates a successful connection to the Web Service.
-112 No valid recipients added or missing fax number
-123 No valid documents attached
-150 Internal System Error
-1002 Number of types does not match number of document sizes string
-1003 Authentication error
-1004 Missing file type
-1005 Transaction does not exist
-1007 Size value is not numeric or not greater than 0
-1008 Total sizes does not match filesdata length
-1009 Image not available (may happen if the 'delete fax after completion' feature is active)
-1030 Invalid Verb or VerbData
-3001

Invalid MessageID

-3002

From parameter is larger than image size

-3003

Image doesn't exist

-3004

TIFF file is empty

-3005

Chunk size is smaller than 1

-3006

Max item is smaller than 1

-3007

No permission for this action (In inbound method GetList, LType is set to AccountAllMessages or AccountNewMessages, when the username is not a Primary user)

Appendix B - Special formats

FaxNumber - Input

See How to format fax numbers in Interfax.

FaxNumber - Output (canonical format)

Interfax system converts any fax number into a standard format. This format is then returned by all status related methods.

The format is: 00 <Country-Code> <AreaCode> <Local number>.

Example: A number in New York, NY, USA will look like: 0012123456789, where:

00 is a constant;
1 is the USA country code;
212 is New York area code;
3456789 is the local number.

FileData

This is a variable-size byte array. Normally it is a buffer obtained from a file image, such as a Word document, PDF, etc.

Examples for creating such array in various development environments and languages can be downloaded off Interfax web site.


XML Status Data

The top level node in the XML buffer is Faxlist. Each Faxlist may contain several FaxItem children. Each FaxItem has several childnodes, as shown below:

<Faxlist>
       <Faxitem>
<TransactionID>
TransactionID</TransactionID>
<DestinationFax>
DestinationFax</DestinationFax>
<SubmitTime>
SubmitTime *</SubmitTime>
<PostponeTime>
PostponeTime * **</PostponeTime>
<CompletionTime>
CompletionTime * **</CompletionTime>
<PagesSubmitted>
PagesSubmitted</PagesSubmitted>
<PagesSent>
PagesSent (single digit precision)</PagesSent>
<Subject>
Subject</Subject>
<Duration>
Duration</Duration>
<RemoteCSID>
RemoteCSID</RemoteCSID>
<Status>
Status</Status> <Contact>Contact</Contact>
<CostPerUnit>
CostPerUnit</CostPerUnit>
<JobID>
JobID</JobID>
<PageHeader>
PageHeader</PageHeader>
<PageOrientation>
PageOrientation</PageOrientation>
<PageResolution>
PageResolution</PageResolution>
<PageSize>
PageSize</PageSize>
<ParentTransactionID>
ParentTransactionID</ParentTransactionID>
<Priority>
Priority</Priority>
<RenderingQuality>
RenderingQuality</RenderingQuality>
<ReplyEmail>
ReplyEmail</ReplyEmail>
<RetriesToPerform>
RetriesToPerform</RetriesToPerform>
<SenderCSID>
SenderCSID</SenderCSID>
<TrialsPerformed>
TrialsPerformed</TrialsPerformed>
<Units>
Units (double digit precision)</Units>
</Faxitem>
<Faxitem>
<TransactionID>
TransactionID</TransactionID>
<DestinationFax>
DestinationFax</DestinationFax>
<SubmitTime>
SubmitTime *</SubmitTime>
<PostponeTime>
PostponeTime * **</PostponeTime>
<CompletionTime>
CompletionTime * **</CompletionTime>
<PagesSubmitted>
PagesSubmitted</PagesSubmitted>
<PagesSent>
PagesSent</PagesSent>
<Subject>
Subject</Subject>
<Duration>
Duration</Duration>
<RemoteCSID>
RemoteCSID</RemoteCSID>
<Status>
Status</Status>
<Contact>
Contact</Contact>
<CostPerUnit>
CostPerUnit (double digit precision)</CostPerUnit>
<JobID>
JobID</JobID>
<PageHeader>
PageHeader</PageHeader>
<PageOrientation>
PageOrientation</PageOrientation>
<PageResolution>
PageResolution</PageResolution>
<PageSize>
PageSize</PageSize>
<ParentTransactionID>
ParentTransactionID</ParentTransactionID>
<Priority>
Priority</Priority>
<RenderingQuality>
RenderingQuality</RenderingQuality>
<ReplyEmail>
ReplyEmail</ReplyEmail>
<RetriesToPerform>
RetriesToPerform</RetriesToPerform>
<SenderCSID>
SenderCSID</SenderCSID>
<TrialsPerformed>
TrialsPerformed</TrialsPerformed>
<Units>
Units (single digit precision)</Units>
</Faxitem>
</Faxlist>

* Date-Time format is yyyy/mm/dd HH:mm:ss
** If unavailable (e.g., not postponed, not completed), null field will be returned
For explanation of fields see FaxStatusEx method above.



About | Contact | Privacy | Terms | Partners | Login | System Status

© Interfax Inc