FaxQuery2 – InterFAX Developer Documentation

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

Description

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

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

Formal Definition

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

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
	Subject	QueryCondition	Search by ‘Subject’ property. Case insensitive.
	FaxNumber	QueryCondition	Search by destination fax number
	DateFrom	DateTime	Search by date range of submission time, from this value
	DateTo	DateTime	Search by date range of submission time, to this value
	UserID	QueryCondition	Search by the submitting user’s username. If the username calling this method is a ‘Primary’ user, any user in the account can be queried for. If the username calling this method is a ‘Normal’ user, only its own username can be queried for. Case insensitive.
	ReplyAddress	QueryCondition	Search by the ‘ReplyAddress’ (email address to which a confirmation is returned) property. Case insensitive.
	TransactionID	QueryCondition	Search by a fax transaction ID
	ParentTransactionID	QueryCondition	Search by a fax’s parent transaction ID. Useful for retrieving all faxes in a broadcast.
	Status	QueryCondition	Search by the result of a fax’s transmission. For all possible values, see InterFAX Error Codes. Quick reminder: negative values means faxes still being processed; zero means successful faxes; positive values means failed faxes.
	ShowHiddenTransactions	Boolean	If `True`, the query will include outgoing fax items which are hidden. If `False`, the query will exclude any outgoing fax items which were marked as hidden.
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	Integer	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

QueryCondition definition

Name	Type	Comments
Verb	`Equals`, `GreaterThan`, `GreaterOrEqual`, `LessThan`, `LessOrEqual`, `Like`, `IncludedIn`, `Between`	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. 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

Output

Name		Type	Comments
FaxQuery2Result
	ResultCode	Integer	The result code of the operation: 0 for success, otherwise an error code indicating what went wrong. See Error Codes, below. All errors are listed in Appendix A. Note that this refers to the success/failure of placing a query, NOT to the result of fax transmission.
	FaxItems	Array of FaxItemEx2	The list of fax items as per the filter criteria. See FaxItemEx2
	Stats	Array of StatusCount	The list of fax statuses and, per status, how many returned fax items have that status. See StatusCount
	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

FaxItemEx2 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 email address to which a confirmation message is to be sent; if multiple values are 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 Definition

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.