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

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 As provided during registration
Password String As provided during registration
QueryForm Structure The values in this structure define the returned population
Subject Search by ‘Subject’ property
Verb Equals, GreaterThan, GreaterOrEqual, LessThan, LessOrEqual, Like, IncludedIn, Between Read more regarding verb definitions
VerbData String Case insensitive. 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.
FaxNumber Search by destination fax number
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.
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 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.
Verb Equals, GreaterThan, GreaterOrEqual, LessThan, LessOrEqual, Like, IncludedIn, Between Read more regarding verb definitions
VerbData String Case insensitive. Use % as a wildcard for the ‘Like’ operator. Use commas as delimiters for the ‘IncludedIn’ and ‘Between’ operators.
ReplyAddress Search by the ‘ReplyAddress’ (email address to which a confirmation is returned) property
Verb Equals, GreaterThan, GreaterOrEqual, LessThan, LessOrEqual, Like, IncludedIn, Between Read more regarding verb definitions
VerbData String Case insensitive. Use % as a wildcard for the ‘Like’ operator. Use commas as delimiters for the ‘IncludedIn’ and ‘Between’ operators.
TransactionID Search by a fax transaction ID
Verb Equals, GreaterThan, GreaterOrEqual, LessThan, LessOrEqual, Like, IncludedIn, Between Read more regarding verb definitions
VerbData String Use % as a wildcard for the ‘Like’ operator.
ParentTransactionID Search by a fax’s parent transaction ID. Useful for retrieving all faxes in a broadcast.
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.
Status 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.
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.
ShowHiddenTransactions Boolean
QueryControl The values in this structure define how the population is returned
OnlyParents Boolean Limit display to transactions which 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 Sort by this property
AscOrderDirection Boolean Sort in ascending order?
ReturnItems Boolean Should full details regarding each fax be returned?
ReturnStats Boolean Should statistical (not detailed) information regarding success/failure/error types be returned?

Output

StatsArray of StatusCountSee below

Name Type Comments
ResultCode Integer 0= OK; less than 0 = Error, see Appendix A. Note that this refers to the success/failure of placing a query, NOT to the result of fax transmission.
FaxItems Array of FaxItem Ex2. See 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

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 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 Yor 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

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