Fax for Agents
Send a fax
Menu
Documentation Quickstart

Quickstart

Updated

Five calls from a terminal. Everything below runs on the sandbox with a test key, so nothing leaves the box and nothing is charged.

Connect your assistant in one paste

Not at a terminal, or using an assistant? Paste this line into it and it does the five steps below for you, signed in through the browser, in the sandbox. The setup page has the line for each kind of assistant.

Read https://faxforagents.com/setup.md and set up Fax for Agents for me. Start in Sandbox.

1. Get a test API key

Sign in at app.faxforagents.com with a magic link, a passkey, GitHub or Google. Your organization comes with a sandbox wallet of $100.00 test credit. Open API keys and create one. The secret starts with ffa_test_ and is shown once.

Starting credit as of 2026-11-02. Source and method: sandboxStartingCredit.

Shell 
export FFA_KEY=ffa_test_...
export FFA=https://api.faxforagents.com/v1

2. Create a document

The fastest way is to let the service render text. A PDF goes through an upload session instead, shown on the send page.

Shell 
curl -s $FFA/documents \
  -H "Authorization: Bearer $FFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Purchase order 4411\n\nPlease confirm by return fax.", "filename": "po-4411"}'

The answer carries the document id (doc_...), its sha256 and its page count. An encrypted or unreadable file is refused with a named code and nothing is stored.

3. Quote it

Shell 
curl -s $FFA/fax-quotes \
  -H "Authorization: Bearer $FFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_id": "doc_...", "to": "+15550000001"}'

The quote binds the document hash, the destination, the sender, the pages and the amount for ten minutes. On the sandbox the amount is $0.000. +15550000001 is the sandbox number that always delivers. The sandbox page lists the others. The limits page has the life of a quote and every other limit.

4. Send it

Shell 
curl -s $FFA/faxes \
  -H "Authorization: Bearer $FFA_KEY" \
  -H "Idempotency-Key: quickstart-1" \
  -H "Content-Type: application/json" \
  -d '{"quote_id": "quote_..."}'

The answer is the job, state queued. Run the same call again with the same Idempotency-Key and you get the same job back with Idempotent-Replayed: true, not a second fax.

5. Read the receipt

Shell 
curl -s $FFA/faxes/fax_.../receipt -H "Authorization: Bearer $FFA_KEY"

Within a worker pass the sandbox job moves from queued through active to delivered. The receipt then lists the provider reference, the pages, the document hash, the amount captured and the time. While the fax is queued or active, the receipt endpoint returns HTTP 409 with error code conflict. Poll GET /v1/faxes/{id} for the state before requesting the receipt. The word delivered never appears before the evidence does.

Next

  • Register a webhook and verify its signature, so you do not have to poll. That takes a key with the scope webhook:admin.
  • Rehearse a busy line, a partial delivery and an unknown outcome on the sandbox.
  • Connect Claude Code or Cursor to the MCP server and do the same five steps as tool calls.
  • Fund the live wallet when you are ready. A live send needs an approval or a policy.

From the blog