faxes

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.

post/fax/{id}/cancel

Request

  • Base URL: https://api.pinnacle.sh
  • URL: https://api.pinnacle.sh/fax/{id}/cancel
  • Auth: API key in header PINNACLE-API-KEY

Path parameters

idstring uuid required

Fax ID returned by send, list, or a fax webhook.

Response

Fax cancelled before transmission started.

idstring uuid required
direction'INBOUND' | 'OUTBOUND' required

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

fromstring required

Sender number in E.164 format.

tostring required

Recipient number in E.164 format.

status'PREPARING' | 'SUBMITTING' | 'SUBMISSION_UNKNOWN' | 'QUEUED' | 'PROCESSING' | 'SENDING' | 'RECEIVING' | 'DELIVERED' | 'RECEIVED' | 'FAILED' | 'CANCELLED' required

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 required

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.

durationSecondsnumber double required

Total transmission duration in seconds.

partialContentboolean required

Whether only part of the document was delivered, including when an earlier part succeeded before a later part failed.

failureReason'MEDIA_PREPARATION_FAILED' | 'MEDIA_PREPARATION_INTERRUPTED' | 'INSUFFICIENT_CREDITS' | 'SUBMISSION_UNCONFIRMED' | 'SUBMISSION_REJECTED' | 'DELIVERY_FAILED' required

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.
costnumber double required

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

reservedCostnumber double required

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.

billingStatus'PENDING' | 'SETTLED' required

Billing state for the fax.

hasMediaboolean required

Whether Pinnacle has archived the fax document.

createdAtstring date-time required
updatedAtstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.