Skip to main content
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.
  • 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 and in the machine-readable openapi.json.
  • Sandbox is always on. The moment you register an account, your sandbox environment accepts POST /faxes with a sandbox key. See 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. The response returns immediately with a fax_<ULID> 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.

​
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 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. For signature verification recipes in several languages, see 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.
  • 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.
  • 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.
  • 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 and 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.
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 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.
  • 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 — register an account, send your first sandbox fax in under a minute.
  • API reference — every endpoint, request shape, and response schema.
  • Webhooks — event types, delivery guarantees, signature verification.
  • Errors — every error code with cause and next action.
  • HIPAA — the compliance boundary, the BAA click-through, and what mintfax’s commitments cover.
  • Build faxing into your SaaS product — multi-tenant patterns, credential management, per-customer webhook routing.
  • Compare mintfax to other fax APIs — head-to-head with Sinch, Telnyx, Documo, and eFax Developer.
  • For startups and For healthtech — segment framings for the two teams mintfax was built for first.
Last modified on July 24, 2026