Skip to navigation
API ReferenceFax (HIPAA only)

Cancel Fax

Cancel an outbound fax before transmission starts.

Cancellation stops queued preparation and every unsent part, releases the credit reservation, and changes the status to CANCELLED. Repeating a successful cancellation returns the same fax.

Cancellation is unavailable for inbound faxes, completed faxes, and SUBMISSION_UNKNOWN faxes. Pinnacle returns 409 once transmission may have started, even when later parts remain unsent.

HIPAA only: this endpoint exists only in Pinnacle’s HIPAA cell and is unavailable at https://api.pinnacle.sh.

Only a fax ID owned by your team is accepted. Unknown IDs return 404.

Authentication

PINNACLE-API-KEYstring
API Key authentication via header

Path parameters

idstringRequiredformat: "uuid"
Fax ID returned by send, list, or a fax webhook.

Response

Fax cancelled before transmission started.
idstringformat: "uuid"
directionenum

OUTBOUND for faxes sent by your team or INBOUND for faxes received by your team.

Allowed values:
fromstringformat: "^\+[1-9]\d{9,14}$"
Sender number in E.164 format.
tostringformat: "^\+[1-9]\d{9,14}$"
Recipient number in E.164 format.
statusenum

Current state of the fax:

  • PREPARING: Pinnacle is downloading, validating, converting, splitting, or archiving the document.
  • SUBMITTING: The fax is waiting for transmission to start.
  • SUBMISSION_UNKNOWN: Transmission may have started, but Pinnacle cannot confirm it. The fax is not retried automatically.
  • QUEUED: The outbound fax is queued for transmission.
  • PROCESSING: The outbound document is being processed.
  • SENDING: The outbound fax is being transmitted.
  • RECEIVING: An inbound fax is in progress.
  • DELIVERED: Every outbound part was delivered.
  • RECEIVED: The inbound fax was received and archived.
  • FAILED: Preparation, submission, or delivery failed. partialContent indicates whether any pages were transmitted.
  • CANCELLED: The outbound fax was cancelled before transmission started.
pagesinteger>=0
Transmitted page count across the fax. This can be zero before transmission and can include only transmitted pages after a partial failure. Outbound documents can contain at most 3,500 pages.
durationSecondsdouble>=0
Total transmission duration in seconds.
partialContentboolean
Whether only part of the document was delivered, including when an earlier part succeeded before a later part failed.
failureReasonenum

Stable failure category, or null when no failure is recorded:

  • MEDIA_PREPARATION_FAILED: The source was unavailable, invalid, unsupported, over a limit, or could not be rendered.
  • MEDIA_PREPARATION_INTERRUPTED: Preparation could not be completed after retries.
  • INSUFFICIENT_CREDITS: The team's available credits could not cover the prepared page count.
  • SUBMISSION_UNCONFIRMED: Transmission may have started, so Pinnacle will not retry automatically.
  • SUBMISSION_REJECTED: Transmission could not start.
  • DELIVERY_FAILED: Delivery failed or a transmitted part did not match the expected page count.
costdouble>=0

Settled fax cost in USD, calculated at $0.025 per final transmitted page. Quality does not change the rate.

reservedCostdouble>=0

Credit reserved after document preparation for an unsettled outbound fax, in USD. This equals $0.025 multiplied by the prepared page count, regardless of quality, and is zero while status is PREPARING.

billingStatusenum

PENDING while a reservation or uncertain submission remains open; SETTLED after final charging, refund, or cancellation.

Allowed values:
hasMediaboolean
Whether Pinnacle has archived the fax document.
createdAtstringformat: "date-time"
updatedAtstringformat: "date-time"

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
500
Internal Server Error
503
Service Unavailable Error