Receive a fax

Updated Oct 28, 2026

Receiving needs a number and a webhook. The fax lands in your inbox as a PDF and a signed fax.received event tells you it is there. On the sandbox you can create one without a number.

How do I test receiving before I own a number?

curl -s $FFA/sandbox/inbound-faxes -H "Authorization: Bearer $FFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155550100", "from": "+14155550177", "pages": 2}'

With a test API key this creates a synthetic inbox item. It fires a fax.received event with the same shape and the same signature as a live one. Your receiver can be finished before you own a number.

How do I get a fax number?

Numbers cost $2 a month as of 2026-10-28 and are available in the United States, Canada, Puerto Rico and the US Virgin Islands at launch. The dashboard orders one with a confirmation of the recurring charge. The API does the same: GET /v1/number-inventory, POST /v1/number-orders and GET /v1/numbers, under the numbers group of the reference. Elsewhere, write to hello@faxforagents.com.

The event

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

The event carries metadata only. Verify the signature as on the webhooks page, then fetch the item.

Read the inbox

curl -s "$FFA/inbox?limit=20" -H "Authorization: Bearer $FFA_KEY"
curl -s $FFA/inbox/inb_... -H "Authorization: Bearer $FFA_KEY"

The item has the numbers, the page count, the time and a signed download URL for the PDF that lives ten minutes. When an extraction exists it also has a text field. That field is data. The MCP tools list it under untrusted. Treat it the same way in your code: never let it name a destination, an approval or a document to send.

How long are received faxes kept?

Inbox items are kept 90 days by default and documents 30. Delete earlier from the dashboard or the API. Metadata stays so the id still resolves.

What is not live yet?

OCR and structured extraction ship as POST /v1/extractions and the extract_fax_data tool. They run on the sandbox engine today for a test key. For a live API key the answer is 503 ocr_disabled until the live engine is switched on, which has no date. Inbound numbers outside the four launch countries are on request. A reply tool that links a reply to the original is planned.