faxes

Send Fax

Send one PDF, TIFF, JPEG, PNG, DOC, DOCX, RTF, or TXT document from a configured fax number.

HIPAA only: this endpoint exists only in Pinnacle's HIPAA cell. Complete HIPAA onboarding and use the connection details provided by Pinnacle. It is not available at https://api.pinnacle.sh.

Availability: from must be an enabled fax number owned by your team. Fax sending is unavailable for development-mode teams and sandbox numbers. Each request accepts exactly one document; cover pages and per-request webhook URLs are not supported.

Source URL: mediaUrl must be a publicly reachable HTTPS URL on port 443. Signed query parameters are supported. URLs with credentials, redirects, private or local network addresses, and non-200 responses are rejected. Downloads must complete within 30 seconds.

Document limits: the document must contain 1–3,500 pages and be no larger than 50 MB. Documents over 350 pages are split automatically and remain one fax in the API. File extensions and response headers do not override file validation.

Document safety: encrypted files, macros, ActiveX controls, embedded objects, symbolic links, unsafe archive paths, and malformed documents are rejected.

Quality: HIGH is the default and recommended choice for most documents. Use NORMAL when speed matters more than detail, VERY_HIGH for small text and fine lines, ULTRA_LIGHT for image-heavy documents, or ULTRA_DARK for text-heavy documents.

Asynchronous processing: the request returns 202 after preparation is queued. Downloading, validation, conversion, splitting, and archival happen afterward. A 202 response does not mean the document is valid or delivered. Watch FAX.STATUS webhooks or retrieve the fax for the final result. The initial status is PREPARING, reservedCost is zero, and hasMedia is false.

Multipart delivery: the original id identifies the complete fax across list, detail, cancellation, billing, media, and webhooks. Parts are sent in order. If a part fails, later parts are not sent. The fax becomes FAILED, and partialContent is true if any earlier pages were transmitted.

Pricing: sent and received faxes cost $0.025 per transmitted page. Quality does not change the rate. Pinnacle reserves the estimated cost after preparation, charges only for transmitted pages, and returns unused reserved credits. If your balance is too low, the fax becomes FAILED with failureReason: INSUFFICIENT_CREDITS.

Delivery uncertainty: Pinnacle does not automatically retry a fax after transmission may have started, which prevents duplicate delivery and charges. If transmission cannot be confirmed, status becomes SUBMISSION_UNKNOWN while Pinnacle reconciles the fax.

Idempotency: Idempotency-Key is optional. Without it, each request creates a new fax, including retries. For retry-safe sending, generate a UUID for each intended fax and retain it until the outcome is known. After a client timeout, retry with the same key and identical body. The key is scoped to your team and covers from, to, mediaUrl, and quality. Reusing it with an identical body returns the existing fax; changing any of those fields returns 409.

post/fax

Request

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

Headers

Idempotency-Keystring

Optional unique key for one logical send. Without it, every request creates a new fax. Use 1–128 ASCII letters, numbers, periods, underscores, or hyphens. Reuse it only with the identical from, to, mediaUrl, and effective quality; any change returns 409.

Request body

fromstring required

Fax-enabled, non-sandbox number owned by your HIPAA team, in E.164 format (+ followed by 10–15 digits; the first digit cannot be zero). The number must remain enabled and configured through preparation. Fax sending is unavailable to development-mode teams.

tostring required

Recipient fax number in E.164 format (+ followed by 10–15 digits; the first digit cannot be zero).

mediaUrlstring uri required

Public HTTPS URL on port 443 for one PDF, TIFF, JPEG, PNG, DOC, DOCX, RTF, or TXT document. The URL must contain 9–8,192 characters, including signed query parameters. Usernames, passwords, redirects, private or local addresses, IPv6-only hosts, and non-200 responses are rejected.

The origin must complete the download within 30 seconds and return no more than 16 KiB of response headers. If present, Content-Length must be a non-negative decimal integer no greater than 50,000,000, and Content-Type must be one of the accepted types listed in the endpoint description. The source and processed document must each be no larger than 50,000,000 bytes. The document must contain 1–3,500 pages.

A permitted URL extension or Content-Type is not sufficient: file signatures and structure must identify a supported format. JPEG/PNG images are limited to 250,000,000 pixels and TIFF images to 2,000,000,000 pixels. DOCX archives must be non-encrypted and free of macros, ActiveX controls, embedded objects, symbolic links, and unsafe paths; ZIP64 and multi-disk containers are not accepted. See the endpoint description for the complete DOCX archive and document-processing limits.

quality'NORMAL' | 'HIGH' | 'VERY_HIGH' | 'ULTRA_LIGHT' | 'ULTRA_DARK'

Rendering profile used for the fax:

  • NORMAL: Lower detail for faster transmission.
  • HIGH: Balanced quality and processing time. This is the default.
  • VERY_HIGH: Higher detail for small text and fine lines.
  • ULTRA_LIGHT: Highest detail for image-heavy documents.
  • ULTRA_DARK: Highest detail for text-heavy documents.

Quality does not change Pinnacle's $0.025 per-page price.

Response

Fax preparation durably queued for asynchronous processing.

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.