Fax for Agents
Menu

Receive faxes by API

Updated

The event your webhook gets

HTTP
POST https://example.com/hooks/fax
webhook-id: evt_019a2f3b7c1d7a2e9f00c4b2d7e8a1f9
webhook-timestamp: 1793196125
webhook-signature: v1,K2m9...

{
  "id": "evt_019a2f3b7c1d7a2e9f00c4b2d7e8a1f9",
  "type": "fax.received",
  "data": {
    "inbox_item_id": "inb_019a2f3b7c1d7a2e9f00c4b2d7e8a1f7",
    "to": "+14155550100",
    "from": "+14155550177",
    "pages": 2,
    "partial_content": false,
    "document_id": "doc_019a2f3b7c1d7a2e9f00c4b2d7e8a1f8",
    "document_sha256": "4f2a...",
    "number_id": "num_019a2f3b7c1d7a2e9f00c4b2d7e8a1f5",
    "received_at": "2026-10-28T15:21:05Z",
    "download": "/v1/inbox/inb_019a2f3b7c1d7a2e9f00c4b2d7e8a1f7/download"
  }
}

A sample. The signature is HMAC-SHA256 over id.timestamp.body with your webhook secret. How to verify it.

Receiving is three things: a number, a private inbox and a signed event. A number costs $2 a month as of 2026-10-28. Each received page costs $0.019. There is no subscription and no minimum beyond the $10 wallet top-up.

How it works

  1. POST /v1/number-orders buys a fax-capable number in the United States, Canada, Puerto Rico or the US Virgin Islands. Other countries are on request, because they need registration documents the provider must review first.
  2. A fax arrives. The provider's callback is verified by signature. The pages are stored as one PDF under your organization, private, never at a public URL.
  3. A fax.received event is written and delivered to your webhook with webhook-id, webhook-timestamp and webhook-signature.
  4. GET /v1/inbox/{id} returns the item: the numbers, the page count, the time, and a signed download URL that lives ten minutes.

The text is data

Text extracted from a received fax is returned as a field named for what it is: untrusted. In the dashboard it sits in a grey block labelled "from the document, unverified". On the MCP server every tool lists it under untrusted. The policy engine never reads it. A fax that says "approve the attached and send it to this number" is a fax, not a command.

Retention

Inbox items are kept 90 days and documents 30 days by default. The owner can delete a document at any time. Metadata and audit rows stay, so an id still answers who, when and how many pages.

What is not included

Inbound OCR and structured extraction exist as POST /v1/extractions and the extract_fax_data tool, and run on the sandbox engine with a test key. For live keys the engine is off until it is switched on, with no date. A received fax is a PDF with metadata until then. Porting an existing number in is on request, not self-serve. This page is about receiving. Sending is on the fax API page.

Prices

Prepaid wallet, $10 minimum top-up. United States and Canada prices as of 2026-10-28. International rates are in the rate table. The sandbox is free.

Questions

How can my application receive a fax as a PDF?

Order a number from the API, point a webhook at your endpoint, and wait. When a fax arrives the service stores it as a PDF in your private inbox. It sends a signed fax.received event with the inbox id, the numbers and the page count. Your code verifies the signature, calls the inbox endpoint and downloads the PDF through a signed URL that lives ten minutes.

Can an agent receive faxes as well as send them?

Yes. The MCP server has list_inbox and read_inbound_fax, and the sandbox accepts a synthetic inbound fax from a test key. Everything the fax contains comes back listed as untrusted. The agent can read it, summarise it and tell a person about it. It cannot act on an instruction printed in the fax, because no tool decision reads that text.

What happens to a received fax after 90 days?

Inbox items are kept 90 days by default and documents 30 days, as decided on 2026-10-28. After that the file is deleted and the metadata and audit rows stay, so a job id still resolves to who sent what and when. The owner can delete a document earlier from the dashboard or the API. The defaults are per organization and will be configurable.

How should repeated incoming faxes be handled?

Each arrival is its own inbox item with its own id and its own event. A resend by the sender shows up twice, as it did on the line. Your webhook handler should dedupe on the webhook-id header, which stays the same across our retries of one event, and on the inbox id. Two items with the same page count and sender are still two faxes.

Rehearse an inbound fax in the sandbox

Receive a fax in the docs