Cancel a Fax

Using the POST /faxes/{fax_id}/cancel endpoint, you can ATTEMPT to cancel a SINGLE fax that was submitted for delivery. In order to make this call you must pass in the following:

• The valid fax_id of the fax selected for deletion. If you do not know the fax_id for the fax you wish to cancel, you can make a call to any of the “listing” endpoints in the Production Faxing API, such as GET /faxes/sent to obtain it.
• The user-id header. This validates that the fax selected for cancellation actually belongs to the specified user.

There are no optional parameters in this call.

Attempting to cancel a fax is dependent on many factors, primarily the timeliness of the submission. Cancelling a fax after delivery is impossible and would result in an appropriate error message returned by the endpoint.

Most commonly a request submitted in a timely manner will be accepted and the fax transmission will be halted/interrupted correctly. If the request is accepted, you receive an HTTP Status Code of 202 – Accepted, indicating that the request was properly logged. For further status, you need to call the GET /faxes/{fax_id}/metadata endpoint.

It should be understood that a possible use case, due to eFax processing speeds, is that a fax may complete delivery between the time a request is submitted and processing of the request. In this case, you would receive a successful response to this endpoint when in fact the fax is not cancelled. Thus, a 202 is NOT a confirmation of cancellation, only a confirmation of receipt of the request. The ultimate disposition of the fax will be reflected in the /metadata endpoint.

If the request conflicts with the status of the fax in question, then you receive an HTTP Status Code of 409 – Conflict, indicating that the request cannot be fulfilled, since the fax was already delivered. In this case, a custom transaction-id is returned in the header, with an error message in the response body that states “fax already completed messaging.”

For a full list of possible return errors, refer to the POST /faxes/{fax_id}/cancel endpoint in the Fax Services specification.