API ReferenceFax (HIPAA only)

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:** reuse the same `Idempotency-Key` and identical body after a client timeout. The key is scoped to your team and covers `from`, `to`, `mediaUrl`, and `quality`. Reusing it with an identical body returns the existing logical fax; changing any of those fields returns 409 and never sends another fax.

Authentication

PINNACLE-API-KEYstring
API Key authentication via header

Headers

Idempotency-KeystringRequiredformat: "^[A-Za-z0-9._-]+$"1-128 characters

Unique key for one logical send. 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

This endpoint expects an object.
fromstringRequiredformat: "^\+[1-9]\d{9,14}$"11-16 characters

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.

tostringRequiredformat: "^\+[1-9]\d{9,14}$"11-16 characters

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

mediaUrlstringRequiredformat: "uri"9-8192 characters

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.

qualityenumOptional

Rendering profile applied to the fax. Defaults to HIGH. Higher-detail profiles can take longer to process but do not change the $0.025 per-page price or any document limit.

Response

Fax preparation durably queued for asynchronous processing.
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