FaxQuery4 – InterFAX Developer Documentation

API Documentation > SOAP API > Outbound Fax Reference > SOAP Method Reference > FaxQuery4

Table of Contents

Description

This is an advanced and extremely flexible method for querying outbound faxes. It is based on querying for query-type/value pairs (called “Verb” and “VerbData” respectively).

The difference with the FaxQuery3 method is that in FaxQuery4 the field to search by is included in the QueryConditionEx structure, instead of in the QueryForm structure.

Note that this method is rate-limited, as defined under System Limitations

Formal Definition

https://ws.interfax.net/dfs.asmx?op=FaxQuery4

Input

Name		Type	Comments
Username		String	The name of the user authenticating to the API
Password		String	The password for the username
QueryForm		Structure	This structure contains the list of query conditions
	DateFrom	DateTime	Search by date range of submission time, from this value
	DateTo	DateTime	Search by date range of submission time, to this value
	ShowHiddenTransactions	Boolean	If `True`, hidden transactions are included
	Conditions	Array of QueryConditionEx	See QueryConditionEx Definition
QueryControl		Structure	The values in this structure define how and how many results are returned
	OnlyParents	Boolean	Limit display to transactions having a Parent Transaction ID; these are “parents”, that is, broadcasts
	NumOfResults	Integer	How many transactions to return? But note that no more transactions will be returned than the value defined in System Limitations.
	StartingRecord	Long	When returning transactions, start at this record
	OrderBy	`TransactionID`, `SubmitTime`, `CompletionTime`, `Status`, `DestinationFax`, `Subject`, `PagesSent`, `UserID`, `ReplyEmail`, `Contact`	Sort by this property
	AscOrderDirection	Boolean	If `True`, sort in ascending order
	ReturnItems	Boolean	If `True`, full details regarding each fax will be returned
	ReturnStats	Boolean	If `True`, statistical (not detailed) information regarding success/failure/error types will be returned
	UseMainQueue	Boolean	If `True`, the criteria will applied to the main switch group. If `False`, the criteria will be applied to another switch group (not main), according to the users switch node id group settings.

QueryConditionEx Definition

Name	Type	Comments
Field	String	The field to search by: UserID, Subject, FaxNumber, ReplyAddress, Status, ParentTransationID or TransactionID
Verb	`Equals`, `GreaterThan`, `GreaterOrEqual`, `LessThan`, `LessOrEqual`, `Like`, `IncludedIn`, `Between`, `NotEquals`	Read more regarding verb definitions
VerbData	String	Use % as a wildcard for the ‘Like’ operator. Use commas as delimiters for the ‘IncludedIn’ and ‘Between’ operators. To search for a string which includes a comma, precede the comma by a backslash. Case insensitive if the condition applies to Subject, UserID, or ReplyAddress.

Verb Definitions

By using Equals, the system will look up faxes with this property that match the value entered in VerbData
By using GreaterThan, the system will look up faxes with this property that are greater than the value entered in VerbData
By using GreaterOrEqual, the system will look up faxes with this property that are greater than or equal to the value entered in VerbData
By using LessThan, the system will look up faxes with this property that are less than the value entered in VerbData
By using LessOrEqual, the system will look up faxes with this property that are less than or equal to the value entered in VerbData
By using Like, the system will look up all of the faxes with this property that the entered in VerbData is included within
By using IncludedIn, the system will look up faxes with this property that are included in the list of values entered in VerbData
By using Between, the system will look up faxes with this property value between the values entered in VerbData
By using NotEquals, the system will look up faxes with this property that do not match the value entered in VerbData

Output

Name		Type	Comments
FaxQuery4Result
	ResultCode	Integer	0= OK; less than 0 = Error, see Error Codes below. The full list is shown on Appendix A. Note that this refers to the success/failure of placing a query, NOT to the result of fax transmission.
	FaxItems	Array of FaxItemEx3	The list of fax items as per the filter criteria. See FaxItemEx3
	Stats	Array of StatusCount	See StatusCount below
	ErrorsDescriptionHTMLFormat	String	If there is an error in this query, the error description will be displayed in a HTML format
	TotalTransactionsNum	Integer	Indicates the total number of transactions resulted in this query

FaxItemEx3 Definition

Name	Type	Comments
ParentTransactionID	Integer	In case of a Broadcast – the ID of the first item
TransactionID	Integer
SubmitTime	DateTime	Time when the transaction was originally submitted. Always returned in GMT.
PostponeTime	DateTime	Time to which the fax was scheduled for transmission. Always returned in GMT. Returns `'0001-01-01T00:00:00.0000000-00:00'` if not postponed
CompletionTime	DateTime	End time of last of all transmission attempts
UserID	String	InterFAX username of the user who submitted the fax
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; if mutltiple values submitted, only the first is used
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	Priority assigned to the fax
Units	Decimal	Number of units to be billed (pages or tenths of minutes)
CostPerUnit	Decimal	Monetary units, in account currency. Multiply this by ‘Units’ to get the actual cost of the fax.
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	Header overlaid on fax
RetriesToPerform	Short	Retry attempts requested
TrialsPerformed	Short	Retry attempts actually performed
LocaleID	Integer	For internal use
GMTBias	Integer	For internal use
RetriesInterval	Integer	Interval in minutes between retries
UserData	String	Reserved for future use
DeleteAfterUsage	String	Was the fax sent with ‘delete image after usage’ set? Note that this string holds a boolean value of either `Y`or `N` (for historical reasons).
Mode	String	For internal use
NumOfTransactions	Integer	Indicates the number of unique fax files (TIFF’s) associated with this transaction. Examples: – A fax sent to a single recipient will have a value of 1. – In a batch sent to multiple recipients sharing a single document: the parent transaction will have the number of transactions in this batch while child transactions will have a value of 0. – In a batch with individual faxes per recipient (like the one generated from a Word Merge): each child transaction will have a value of 1.
MessageID	String	SMTP message ID of the confirmation email sent after fax completion

StatusCount Definitions

Name	Type	Comments
Status	Integer	Fax status. 0= OK; greater than 0 = Error (See Interfax Error Codes)
Count	Integer	Number of transactions resulting from this query associated with this Status

Error Codes

Value	Description
-150	Internal System Error. An exception occurred at any point in the execution of the web service method.
-310	The logged in user in context is not a primary user. User is not authorized to operate actions on requested UserID.
-666	The user is configured in another switch group
-677	The user does not have any TX service registered
-710	At least one of the two parameters ReturnItems and ReturnStats should be set to true
-1003	Authentication error: the user cannot be authenticated when either the username or the password is incorrect OR any other last error occurred when authenticating the user.
-1011	Too many data requests from the Username. (The maximum frequency of polling for fax status is defined under “System Limitations“.)
-2003	The request from the IP of the machine is not in a valid IP address range.