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.