faxes

Get Fax

Retrieve a fax and a one-hour signed document URL when its media is available.

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

Only faxes owned by your team are accessible. Unknown IDs and records removed by your team's HIPAA retention policy return 404. mediaUrl is null until archival completes and expires one hour after retrieval; request the fax again for a new URL.

get/fax/{id}

Request

  • Base URL: https://api.pinnacle.sh
  • URL: https://api.pinnacle.sh/fax/{id}
  • 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 details.

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
mediaUrlstring uri nullable required

One-hour signed URL for the archived document, or null until media is available. Treat the URL as sensitive because anyone who possesses it can access the document until it expires; request this endpoint again for a fresh URL.

Changes

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