Interfax Inbound Fax Web Service Reference

Sections

Overview
Requirements
Programmer's Guide
Method Reference
     GetList
     GetImageChunk
     MarkMessage
     GetInboundActivity
Appendix A - Error Codes

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.

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

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

Note: Inbound service is NOT automatically opened for you when you register for our developer program. You may request this separately, if you need.

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 inbound fax Web Service WSDL may be accessed at http://ws.interfax.net/inbound.asmx?WSDL or securely at https://ws.interfax.net/inbound.asmx?WSDL.

3.2 Retrieving the inbound fax list

The inbound fax list can be retrieved by calling the method GetList. The GetList request is submitted with list type (all or unread) and MaxItem (the maximum number of items in the list can be up to 100). The list will be in the format of an array that is made up of MessageItems and given by reference from the client.

3.3 Getting the inbound fax image

The fax image can be retrieved by using the GetImageChunk method. The GetImageChunk request is submitted with the MessageID, buffer to place the image in, buffer size (chunk size that you wish to receive) and from (which byte of the image to start at). After the last buffer of the image has been sent, the message will be marked as read.

3.4 Marking inbound messages as read

The client can change the status of the message from 'unread' to 'read' and vice versa. The incoming messages are automatically marked as 'unread' until the client has downloaded the image file completely or marked the message as 'read' by using the MarkMessage method. The MarkMessage request is submitted with the MessageID and a Boolean (true for marking the message as 'read, and false for marking it as 'unread').

4. Method reference

4.1 Method name: GetList

Parameters:

Name	Type	Comments
Username	String	As provided during registration
Password	String	As provided during registration
LType	ListType	Inbound.ListType - Enumeration: `AllMessages` = return all messages for this user; `NewMessages` = return only new messages for this user; `AccountAllMessages` = return all messages for all users under account (username used above must be defined as administrator in the account); `AccountNewMessages`= return new messages for all users under account (username used above must be defined as administrator in the account).
MaxItems	Integer	Maximum items to return, between 1 to 100
objMessageItem	Array	Output parameter: array of MessageItem. NOTE: Items in the inbound queue are returned by the GetList method ONLY if the image associated with them is still available on the Interfax server. Fax images are currently kept for 7 days.
MessageItem Definition
MessageID	Integer	Message ID number
PhoneNumber	String	Interfax phone number
RemoteCSID	String	Sending party CSID (up to 20 characters).
MessageStatus	Integer	0 = OK < 0 = Error, see Interfax Error Codes
Pages	Integer	Number of pages
MessageSize	Integer	Message size in bytes
MessageType	Short	Currently 1 constant
ReceiveTime	DateTime	Time of fax reception
CallerID	String	Sender phone number, if Caller ID available
MessageRecordingDuration	Integer	Duration of inbound fax in seconds

Return value: Integer

0 - OK
< 0 - Error, see Appendix A

4.2 Method name: GetImageChunk

Parameters:

Name	Type	Comments
Username	String	As provided during registration
Password	String	As provided during registration
MessageID	Integer	Message ID of the transaction to download
MarkAsRead	Boolean	`True` - mark as read. `False` - doesn't change the current status
ChunkSize	Long	Buffer size to download
From	Long	Starting point of the image to write to the buffer
Image	Array	Output parameter: byte array of the image part that you requested (according to the buffer size and from start point)

Return value: Integer

0 - OK
< 0 - Error, see Appendix A

4.3 Method name: MarkMessage

Parameters:

Name	Type	Comments
Username	String	As provided during registration
Password	String	As provided during registration
MarkAsRead	Boolean	`True` - mark as read, `False` - mark as unread
MessageID	Integer	Message ID number to download

Return value: Integer

0 - OK
< 0 - Error, see Appendix A

4.4 Method name: GetInboundActivity

Parameters:

Name	Type	Comments
Username	String	As provided during registration; Note: This method can only be used by a "Primary" user.
Password	String	As provided during registration
TimeFrom	DateTime	Start of date range (yyyy-mm-dd); must be no older than 60 days.
TimeUntil	DateTime	End of date range (yyyy-mm-dd)
OnlyMyUser	Boolean	If `true` - return only the current user's activity. If `false` - return activity for ALL users under current account.

Return value: Integer

0 - OK
< 0 - Error, see 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, outbound fax method return codes are included in the table.

Value	Description
(any value greater than 0)	TransactionID. Thinks 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
-1030	Invalid Verb or VerbData
-2040	Invalid date range
-2041	TimeFrom is too old (greater than 60 days)
-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	MaxItem 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)