# Quickstart

> A test key, a document, a quote, a sandbox send and the receipt. Five calls. Nothing leaves the box and nothing is charged.

Page: https://faxforagents.com/docs/quickstart/
Last changed: 2026-10-28

Updated Oct 28, 2026

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](https://app.faxforagents.com/sign-in) 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](https://faxforagents.com/docs/send-fax/).

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](https://faxforagents.com/docs/sandbox/) 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](https://faxforagents.com/docs/webhooks/), so you do not have to poll.
- Rehearse a busy line, a partial delivery and an unknown outcome on the [sandbox](https://faxforagents.com/docs/sandbox/).
- Connect [Claude Code or Cursor](https://faxforagents.com/docs/mcp-setup/) 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](https://faxforagents.com/docs/approvals/) or a [policy](https://faxforagents.com/docs/policies/).

## From the blog

- [How to send a fax in 2026: machine, computer, email or API](https://faxforagents.com/blog/how-to-send-a-fax/)
- [One-time fax: send a single fax with no fax machine](https://faxforagents.com/blog/one-time-fax/)