Fax for Agents
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.

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.

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.

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. Before that the receipt is empty and GET /v1/faxes/{id} shows the state. The word delivered never appears before the evidence does.

Next

  • Register a webhook and verify its signature, so you do not have to poll.
  • 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.