Skip to navigation
API ReferenceFax (HIPAA only)

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.

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 details.
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"
mediaUrlstring or nullformat: "uri"

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.

Errors

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