FaxStatus – UTBox Support

Description

This function provides you with a method of retrieving the status, details and results of fax messages sent. While this is a legitimate method of retrieving results we strongly advise that you take advantage of our callback service (see Section 4), which will push these fax results to you as they are completed.

When making a status request, you must provide at least a BroadcastRef, SendRef or MessageRef. The function will also accept a combination of these to further narrow the request query.

- Limiting by a BroadcastRef allows you to retrieve faxes contained in a group of send requests.

- Limiting by SendRef allows you to retrieve faxes contained in a single send request.

- Limiting by MessageRef allows you to retrieve a single fax message.

There are multiple levels of verbosity available in the request; these are explained in detail below. You can also find full examples in Section 6 of this document.

Request

FaxStatusRequest Parameters:

Name	Required	Type	Description	Default
BroadcastRef		String	User-defined broadcast reference.
SendRef		String	User-defined send reference.
MessageRef		String	User-defined message reference.
Verbosity		String	The level of detail in the status response. Please see below for a list of possible values.	brief

Verbosity Levels:

Value	Description
brief	Gives you an overall view of the messages. This simply shows very high-level statistics, consisting of counts of how many faxes are at each status (i.e. processing, queued, sending) and totals of the results of these faxes (success, failed, blocked).
send	Includes the results from “*brief*” while also including an itemised list of each fax message in the request.
details	Includes the results from “*send*” along with details of the parameters used to send the fax messages.
results	Includes the results from “*send*” along with the sending results of the fax messages.
all	Includes the results from both “*details” and “results*” along with some extra uncommon fields.

Response

The response received depends entirely on the verbosity level specified.

FaxStatusResponse:

Name	Type	Verbosity	Description
FaxStatusTotals	FaxStatusTotals	brief	Counts of how many faxes are at each status. See below for more details.
FaxResultsTotals	FaxResultsTotals	brief	Totals of the end results of the faxes. See below for more details.
FaxMessages	Array of FaxMessage	send	List of each fax in the query. See below for more details.

FaxStatusTotals:

Contains the total count of how many faxes are at each status.

To see more information on each fax status, view the FaxStatus table below.

Name	Type	Verbosity	Description
pending	Long	brief	Fax is pending on the system and waiting to be processed.
processing	Long	brief	Fax is in the initial processing stages.
queued	Long	brief	Fax has finished processing and is queued, ready to send out at the send time.
starting	Long	brief	Fax is ready to be sent out.
sending	Long	brief	Fax has been spooled to our servers and is in the process of being sent out.
pausing	Long	brief	Fax has been told to pause.
paused	Long	brief	Fax is currently paused.
resuming	Long	brief	Fax has been told to resume. After the resume has been confirmed, it is set back to the “sending” status.
stopping	Long	brief	Fax has been told to stop. After the stop has been confirmed, it is set to the “finalizing” status.
finalizing	Long	brief	Fax has finished sending and the results are being processed.
done	Long	brief	Fax has completed and no further actions will take place. The detailed results are available at this status.

FaxResultsTotals:

Contains the total count of how many faxes ended in each result, as well as some additional totals.

To view more information on each fax result, view the FaxResults table below.

Name	Type	Verbosity	Description
success	Long	brief	Fax has successfully been delivered to its destination.
blocked	Long	brief	Destination number was found in one of the block lists.
failed	Long	brief	Fax failed getting to its destination.
totalAttempts	Long	brief	Total attempts made in the reference context.
totalFaxDuration	Long	brief	Total time spent on the line in the reference context.
totalPages	Long	brief	Total pages sent in the reference context.

FaxMessages:

Name	Type	Verbosity	Description
messageRef	String	send
sendRef	String	send
broadcastRef	String	send
sendTo	String	send
status		send	The current status of the fax message. See the FaxStatus table above for possible status values.
FaxDetails	FaxDetails	details	Contains the details and settings the fax was sent with. See below for more details.
FaxResults	Array of FaxResult	results	Contains the results of each attempt at sending the fax message and their connection details. See below for more details.

FaxDetails:

Name	Type	Verbosity	Description
sendFrom	Alphanumeric String	details
resolution	String	details
retries	Integer	details
busyRetries	Integer	details
headerFormat	String	details

FaxResults:

Name	Type	Verbosity	Description
attempt	Integer	results	The attempt number of the FaxResult.
result	String	results	The result of the fax message. See the FaxResults table above for all possible results values.
Error	FaxError	results	The fax error code if the fax was not successful. See below for all possible values.
cost	BigDecimal	results	The final cost of the fax message.
pages	Integer	results	Total pages sent to the end fax machine.
scheduledStartTime	DateTime	results	The date and time the fax is scheduled to start.
dateCallStarted	DateTime	results	Date and time the fax started transmitting.
dateCallEnded	DateTime	results	Date and time the fax finished transmitting.

FaxError:

Value	Error Name
DOCUMENT_UNSUPPORTED	Unsupported document type
DOCUMENT_FAILED_CONVERSION	Document failed conversion
FUNDS_INSUFFICIENT	Insufficient funds
FUNDS_FAILED	Failed to transfer funds
BLOCK_ACCOUNT	Number cannot be sent from this account
BLOCK_GLOBAL	Number found in the Global blocklist
BLOCK_SMART	Number found in the Smart blocklist
BLOCK_DNCR	Number found in the DNCR blocklist
BLOCK_CUSTOM	Number found in a user specified blocklist
FAX_NEGOTIATION_FAILED	Negotiation failed
FAX_EARLY_HANGUP	Early hang-up on call
FAX_INCOMPATIBLE_MACHINE	Incompatible fax machine
FAX_BUSY	Phone number busy
FAX_NUMBER_UNOBTAINABLE	Number unobtainable
FAX_SENDING_FAILED	Sending fax failed
FAX_CANCELLED	Cancelled
FAX_NO_ANSWER	No answer
FAX_UNKNOWN	Unknown fax error

SOAP Faults

This function will throw one of the following SOAP faults/exceptions if something went wrong:

InvalidArgumentsException, NoMessagesFoundException, or InternalServerException.

You can find more details on these faults in Section 5 of this document.