> ## Documentation Index > Fetch the complete documentation index at: https://mintfax.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # The mintfax fax API > What the API does, what ships in the box at every paid tier, and where to go next mintfax is a developer-first fax service. This page is the map: what the API does, what you can expect from the request-response contract, and where each capability lives in these docs. If you are evaluating fax APIs and want to know whether mintfax fits the integration you are about to build, read this end to end. If you are already integrating, use the section links to jump to the reference page you need. ## What the API is * **REST over JSON.** One base URL, `https://api.mintfax.com/v1`. Multipart on `POST /faxes` for file upload; JSON everywhere else. * **Bearer token auth.** One header, `Authorization: Bearer mfx_test_...` for sandbox or `mfx_live_...` for production. No OAuth, no JWT rotation, no signed request scheme. See [Authentication](/docs/authentication). * **One resource per verb.** `POST /faxes` submits a fax. `GET /faxes/{id}` returns the current status. `GET /events` replays the event stream. `POST /webhooks` registers a delivery endpoint. The full endpoint list lives in [API reference](/docs/api-reference/overview) and in the machine-readable [`openapi.json`](https://mintfax.com/docs/openapi.json). * **Sandbox is always on.** The moment you register an account, your sandbox environment accepts `POST /faxes` with a sandbox key. See [Quickstart](/docs/quickstart) for the first-fax path. ## Sending a fax `POST /faxes` accepts a multipart body: a `to` field in E.164 format (leading `+` and country code), a `file` attachment up to 10 MB, and an optional `Idempotency-Key` header. mintfax accepts PDF, DOCX, XLSX, JPG, PNG, TIFF, HTML, and plain text; the full list and per-format notes are in [File types](/docs/file-types). The response returns immediately with a `fax_` identifier and a status of `queued`. The fax then transitions through `submitted`, `in_progress`, and terminates at `delivered` or `failed`. Poll `GET /faxes/{id}` for the current state, or subscribe to webhooks for a push notification when the state changes. International sending is supported end to end. Numbers stay in E.164 throughout the API contract. There is no per-country provisioning step and no separate international product; see [International](/docs/international). ## Receiving events mintfax delivers state changes over webhooks. The event types are `fax.queued`, `fax.sending`, `fax.delivered`, `fax.failed`, `balance.low`, and `balance.topup`. Every payload follows the [Standard Webhooks](https://www.standardwebhooks.com/) specification and carries three headers: `webhook-id`, `webhook-timestamp`, and `webhook-signature`. The signature is HMAC-SHA256 over `{webhook-id}.{webhook-timestamp}.{body}`, keyed by the per-endpoint secret shown once at creation. Every event is also readable through `GET /events` and `GET /events/{id}`, byte-for-byte identical to what was delivered to your endpoint. That means retries, replay, and gap recovery are queries, not incidents. If you missed a webhook, pull the event; if a payload arrives twice, dedupe by `id`. For the full webhook contract, see [Webhooks](/docs/webhooks). For signature verification recipes in several languages, see [Verify requests](/docs/webhooks/verify-requests). ## What ships in the box at every paid tier The one line that distinguishes mintfax from other fax APIs: the integration bundle a modern engineering team expects is standard equipment at every paid tier, not enterprise-only. Concretely: * **Signed webhooks.** Standard Webhooks signature scheme, per-endpoint secret, atomic rotation via `POST /webhooks/{webhook}/rotate-secret`. See [Verify requests](/docs/webhooks/verify-requests). * **Idempotency keys.** Optional `Idempotency-Key` header on `POST /faxes`. Duplicate requests with the same key return the cached response; the same key with a different body returns `409 idempotency_key_reuse`. Keys expire after 24 hours. See [Idempotency](/docs/idempotency). * **Retries with a real error taxonomy.** Automatic retries with backoff of 1m / 3m / 5m / 5m, default 3 attempts, tunable per fax via `max_attempts` in the range 1-5. Every terminal outcome resolves to one of 10 stable, mintfax-owned error codes (`busy`, `no_answer`, `line_quality`, `carrier_busy`, `network_error`, `timeout`, `internal_error`, `invalid_number`, `bad_destination`, `no_route`); carrier identity is never exposed. See [Errors](/docs/errors). * **A sandbox that mirrors live.** Sandbox and live expose the same API contract, with three documented differences (top-ups are simulated, faxes route to a deterministic simulator, live requires a first credit purchase to activate). Sandbox magic numbers force deterministic outcomes like `busy` or `no_answer` for testing. See [Sandbox](/docs/sandbox) and [Sandbox scenarios](/docs/sandbox-scenarios). * **A self-serve BAA.** mintfax operates under a BAA at every paid tier. The dashboard exposes a click-through path that produces a downloadable, executed PDF and writes a durable evidence record. No sales call, no negotiation, no procurement queue. See [HIPAA](/docs/hipaa). None of these are behind an enterprise tier because there is no enterprise tier. Pricing is public, per page, and identical whether you send 1,000 faxes a month or a million; the [pricing page](https://mintfax.com/pricing) lists every tier. ## Statuses, errors, and observability * **Fax statuses:** `queued` → `submitted` → `in_progress` → `delivered` or `failed`. That is the entire state machine. * **Every response carries an `X-Request-Id`.** Errors include the same value as `request_id` in the JSON envelope, so a support ticket carries the identifier that resolves the request in mintfax's logs. * **Error responses are structured.** Each response includes an `error` code, a human-readable `message`, an `action` hint for the caller, and a `docs` URL that points to the error's page. * **Per-attempt visibility.** The fax record's `attempts[]` array records every send attempt with carrier-side outcome and timing. `fax.sending` webhooks fire once per attempt, so a fax that retries twice emits three `fax.sending` events. Per-attempt webhook delivery logs are inspectable via `GET /webhooks/attempts` and re-drivable via `POST /webhooks/attempts/{attempt}/retry`. ## Constraints worth knowing before you build * **Outbound only.** mintfax sends faxes; it does not receive them. No inbound numbers, no fax-to-email, no port-in. * **No official SDK packages.** REST/JSON with an OpenAPI 3.1 spec and language-agnostic curl examples throughout the docs. Node integration notes are in [Node](/docs/node). * **US region storage.** Data is stored in a single US region today; the DPA carries a forward commitment to advance notice on regional changes. ## Where to go next * [Quickstart](/docs/quickstart) — register an account, send your first sandbox fax in under a minute. * [API reference](/docs/api-reference/overview) — every endpoint, request shape, and response schema. * [Webhooks](/docs/webhooks) — event types, delivery guarantees, signature verification. * [Errors](/docs/errors) — every error code with cause and next action. * [HIPAA](/docs/hipaa) — the compliance boundary, the BAA click-through, and what mintfax's commitments cover. * [Build faxing into your SaaS product](/docs/build-into-saas) — multi-tenant patterns, credential management, per-customer webhook routing. * [Compare mintfax to other fax APIs](https://mintfax.com/compare/) — head-to-head with Sinch, Telnyx, Documo, and eFax Developer. * [For startups](https://mintfax.com/for/startups) and [For healthtech](https://mintfax.com/for/healthtech) — segment framings for the two teams mintfax was built for first.