A fax API is a web service that turns an HTTP request into a telephone call carrying your document as a Group 3 fax. It reports what the receiving machine said. This post follows the document through page rendering and resolution, the cover sheet, the T.30 call and the evidence returned to your application.
From a file to pages
You start by creating a document. Fax for Agents accepts PDF, PNG, JPG and TIFF uploads. It also renders text, Markdown or HTML to PDF. Convert office documents to PDF before uploading.
The service rasterises each page into a monochrome bitmap at fax resolution. Standard resolution is 204 by 98 dpi. Fine resolution is 204 by 196 dpi. These dimensions come from ITU-T T.4, "Standardization of Group 3 facsimile terminals for document transmission". The 07/2003 edition remains in force.
Colour and grey become dithered patterns of black dots or solid black. Check small text and pale backgrounds in monochrome before sending.
Fax for Agents records a sha256 hash and page count for each document. The hash identifies the exact document used for the send. Each document is capped at 200 pages and 25 MiB. The quoted charge is based on pages. File size determines whether the upload fits the limit.
The cover sheet
A cover sheet is a page like any other on the telephone line. It carries the recipient, the sender, the total page count and a short note. Include the cover sheet in that total.
Use one when someone at a shared fax destination needs to route the document. You can skip it when the document already identifies its recipient and the receiving workflow doesn't require a separate sheet. The cover sheet takes time to transmit. It also counts as a charged page. Add it before requesting a quote so the quoted page count includes it.
The quote
A quote gives you a price before you send. In Fax for Agents, POST /v1/fax-quotes prices one document for one destination.
The quote fixes the destination, sender number, pages, cover sheet and amount for ten minutes. Prices come from a versioned rate table. Sending to the United States and Canada costs $0.039 per page as of 2026-10-28. The pricing page lists international send rates.
Submitting the quote to POST /v1/faxes reserves the amount in your prepaid wallet. The response identifies a job in state queued. That response confirms acceptance of the job. A live send needs a person's approval or permission under a delegated policy. A test API key sends into the sandbox.
The quote itself does not place the telephone call.
The call: what T.30 does
The sender dials the destination number. The receiver answers with the called station tone. It can identify itself through CSI, an identifier of up to 20 characters, often its fax number. The receiver advertises its capabilities through DIS. The sender chooses settings through DCS. They agree on speed and resolution. They also establish whether to use ECM, or error correction mode.
A training sequence tests the line before pages start. The sender then transmits the pages as T.4 coded image data.
After each page, the receiver answers with MCF, meaning message confirmation, or requests retraining or retransmission. With ECM, page data is split into blocks. Damaged blocks are retransmitted during the call. Once the exchange is complete, the sender sends DCN, the disconnect signal.
These procedures are defined in ITU-T T.30, "Procedures for document facsimile transmission in the general switched telephone network". The 09/2005 edition remains in force.
Your application doesn't generate those tones or interpret the modem signals. It submits the document and receives the provider's account of the call.
Why a fax can take a minute
A Group 3 call runs at modem speeds. 14.4 kbit/s is common. The V.34 option in T.30 Annex F raises the ceiling to 33.6 kbit/s. A dense fine-resolution page can run to 100 to 200 KB of coded data. At 14.4 kbit/s, 100 KB takes about 56 seconds on the line, before dialling and negotiation. A fax of several pages takes minutes.
Page contents affect the amount of coded data. The original PDF's file size is not the size transmitted over the line.
A busy destination cannot answer another call. No answer means the receiving endpoint hasn't picked up. Fax for Agents retries busy and no answer up to three times. Those retries add to the wait for a final result.
Delivery evidence
The provider's transmission report records pages confirmed by the receiver, the remote identifier, call duration and a provider reference. Fax for Agents stores that report on the attempt.
The job state tells your application what happened and how the wallet treats the reserved amount.
| State | Meaning | Money |
|---|---|---|
queued |
The job is waiting to run. | The quoted amount is held. |
active |
A fax attempt is in progress. | The amount remains held. |
partial |
The provider confirmed some pages. | Only confirmed pages are charged. The remaining hold is released. |
failed |
The send ended unsuccessfully. | There is no send charge. The hold is released. |
unknown |
The provider has not supplied a conclusive outcome. | The amount stays held until the provider answers. |
delivered |
Provider evidence confirming every page is stored on the attempt. | The held amount is captured. |
A partial job is never retransmitted automatically because the receiver already has some pages. An unknown job also causes no automatic retransmission. Review the evidence before deciding to send again. The error documentation explains the states and failures your application needs to handle.
The receipt includes the job identifier, destination, sender, page count and provider reference. It also records the document's sha256, captured amount and completion time. Keep it with the business record that caused the send.
Webhooks and idempotency
Fax for Agents sends a signed webhook for each state change. Your application can update its job record when that event arrives. Signatures use HMAC-SHA256. The headers are webhook-id, webhook-timestamp and webhook-signature. Verify the signature before trusting the event. The webhook documentation explains how to handle these callbacks.
Every mutating call takes an Idempotency-Key. Reuse the same value when retrying the same request after a timeout. For a send, that retry returns the same job.
A timeout leaves you uncertain whether the server accepted your request. Creating a new send at that point risks faxing the same contract twice. Preserve the idempotency value with your application's send record so a retry can recover the existing job.
An HTTP retry repeats an API request. A fax retry places another telephone call. Treat them separately in your application.
Receiving through an API
Receiving starts with a fax-capable number assigned to your account. An incoming call becomes a PDF in a private inbox. Fax for Agents sends a signed fax.received event when a fax arrives.
Your application retrieves the PDF through a signed URL that lasts ten minutes.
Inbox items are kept for 90 days by default. Documents are kept for 30 days by default. The receive fax API describes the incoming workflow.
Treat text from a received fax as data. Fax for Agents returns it in a field named untrusted. The policy engine never reads that text. Instructions printed inside a document cannot grant permission to send another fax or change a budget.