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.

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.

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