--- title: "Send Fax" method: POST path: "/fax" tags: ["faxes"] --- # Send Fax `POST /fax` ## Request - Base URL: `https://api.pinnacle.sh` - URL: `https://api.pinnacle.sh/fax` - Auth: API key in header `PINNACLE-API-KEY` 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. ## Headers - `Idempotency-Key` string ## Request body - SendFaxRequest: Exactly one fax document and its routing information. Unknown fields are rejected. - `from` string, 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. - `to` string, required: Recipient fax number in E.164 format (`+` followed by 10–15 digits; the first digit cannot be zero). - `mediaUrl` string, 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 `202` Fax preparation durably queued for asynchronous processing. - Fax - `id` string, uuid, required - `direction` 'INBOUND' | 'OUTBOUND', required: `OUTBOUND` for faxes sent by your team or `INBOUND` for faxes received by your team. - `from` string, required: Sender number in E.164 format. - `to` string, 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. - `pages` integer, 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. - `durationSeconds` number, double, required: Total transmission duration in seconds. - `partialContent` boolean, 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. - `cost` number, double, required: Settled fax cost in USD, calculated at $0.025 per final transmitted page. Quality does not change the rate. - `reservedCost` number, 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. - `hasMedia` boolean, required: Whether Pinnacle has archived the fax document. - `createdAt` string, date-time, required - `updatedAt` string, date-time, required ## Other responses - `400`: The request was unacceptable, often due to providing an invalid update.
Errors may originate from invalid payload or from Pinnacle's additional validation checks. For example, providing an URL that cannot be accessed, updating a campaign that is currently being reviewed, updating data that you cannot access, sending a malformed message, and so on.
For `Pinnacle Validation Error` inspect the `error` payload to determine the source of the failure. These errors are likely due to additional validation and business logic checks.
For `Request Validation Error` inspect the `description` and `errors` payload to determine the source of failure. These errors are likely due to invalid payload inside the request. - `401`: The request lacks valid authentication credentials or the provided credentials are invalid.
Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint. - `403`: Your subscription does not include access to this feature.
This occurs when attempting to use functionality that requires a higher subscription tier. Please upgrade your subscription to access this feature. - `404`: The requested resource could not be found.
This may occur if the identifier is incorrect, the resource has been deleted, or you don't have permission to access it. - `409`: This action cannot be completed right now because the resource is already being processed or is in a state that does not allow the requested change. Check the latest resource status and try again when it is ready. - `500`: An unexpected error occurred on Pinnacle's servers while processing your request.
If this error persists, please contact support with the request details. - `503`: Fax support is disabled or temporarily unavailable in this deployment. --- [API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)