Developer preview

Onetime Fax Developers

Build browserless fax sending into apps, workflows, and agents. Create a job, attach documents, confirm the quote, and send with prepaid credits.

Create an account View reference

Connecting an AI assistant? See the MCP tools.

fax.create

curl https://app.onetimefax.com/api/v1/faxes \
  -H "Authorization: Bearer otf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "recipientNumber": "+14155551212"
  }'

Quickstart

Set up billing once, then send faxes from code without stopping for checkout.

Create your account

Fund the account

Add prepaid credits once in the developer console. Fax sends then charge that balance.

Build the send flow

Create a fax, upload files, poll for the quote, and send from code or an agent.

Fax send reference

The fax API is an async job flow. Credits are charged after documents are counted, when you call send.

1POST /api/v1/faxes creates a draft fax job.
2POST /api/v1/faxes/{id}/files attaches documents. DELETE an attachment to replace it.
3GET /api/v1/faxes/{id} shows file processing and the price.
4POST /api/v1/faxes/{id}/send debits credits and queues delivery. GET the fax again for status.

Implemented endpoints

These are the routes currently available in the developer preview. All API requests use an Authorization: Bearer otf_live_... header.

GET/api/v1/account

Get account balance

Validates an API key and returns the developer account name, credit balance, and key metadata.

Example response

{
  "account": {
    "name": "Acme Operations",
    "creditBalanceCents": 2500,
    "creditBalance": "$25.00"
  },
  "apiKey": {
    "name": "Production",
    "keyPrefix": "otf_live_abcd...",
    "lastUsedAt": "2026-07-03T03:19:09.981Z"
  }
}

POST/api/v1/faxes

Create a fax draft

Creates a durable draft fax for an E.164 recipient number. Files and credit debiting happen in later calls.

Example request

{
  "recipientNumber": "+14155551212"
}

Example response

{
  "fax": {
    "id": "cmr4...",
    "status": "draft",
    "recipientNumber": "+14155551212",
    "createdAt": "2026-07-05T21:20:00.000Z"
  },
  "next": {
    "uploadFile": "/api/v1/faxes/cmr4.../files",
    "status": "/api/v1/faxes/cmr4...",
    "send": "/api/v1/faxes/cmr4.../send"
  }
}

POST/api/v1/faxes/{faxId}/files

Upload a file

Uploads one document to an API fax draft. Send the request as multipart/form-data with a file field.

Example request

curl https://app.onetimefax.com/api/v1/faxes/cmr4.../files \
  -H "Authorization: Bearer otf_live_..." \
  -F "file=@document.pdf"

Example response

{
  "file": {
    "id": "cmr5...",
    "filename": "document.pdf",
    "contentType": "application/pdf",
    "sizeBytes": 123456,
    "status": "uploaded",
    "pageCount": null,
    "order": 1,
    "createdAt": "2026-07-05T21:30:00.000Z"
  },
  "fax": {
    "id": "cmr4...",
    "status": "draft"
  },
  "next": {
    "status": "/api/v1/faxes/cmr4...",
    "send": "/api/v1/faxes/cmr4.../send"
  }
}

DELETE/api/v1/faxes/{faxId}/files/{fileId}

Remove a draft file

Removes an attachment before the fax is sent. Returns 204 with no response body.

Example request

curl -X DELETE https://app.onetimefax.com/api/v1/faxes/cmr4.../files/cmr5... -H "Authorization: Bearer otf_live_..."

Example response

204 No Content

GET/api/v1/faxes/{faxId}

Get fax and quote

Poll until every file is ready and quote is non-null. After sending, this route reports delivery status.

Example response

{
  "fax": {
    "id": "cmr4...",
    "recipientNumber": "+14155551212",
    "status": "draft",
    "createdAt": "2026-07-05T21:20:00.000Z",
    "files": [{
      "id": "cmr5...", "filename": "document.pdf",
      "sizeBytes": 123456, "pageCount": 2,
      "status": "ready", "order": 1,
      "createdAt": "2026-07-05T21:30:00.000Z"
    }],
    "pageCount": 2,
    "quote": {
      "priceCents": 500,
      "creditBalanceCents": 1000,
      "shortfallCents": 0
    },
    "creditsConsumedCents": null
  }
}

POST/api/v1/faxes/{faxId}/send

Send a fax

Charges the quoted amount and queues delivery. Retrying the same fax ID returns the original charge without another debit. Processing files return 409; insufficient credits return 402 with the shortfall and top-up path.

Example request

curl -X POST https://app.onetimefax.com/api/v1/faxes/cmr4.../send -H "Authorization: Bearer otf_live_..."

Example response

{
  "fax": { "id": "cmr4...", "status": "queued" },
  "creditsConsumedCents": 500,
  "creditBalanceCents": 500,
  "replayed": false,
  "next": { "status": "/api/v1/faxes/cmr4..." }
}

Edit a fax draft with MCP

Connect ChatGPT or another MCP client tohttps://app.onetimefax.com/mcpand authorize your own developer account with OAuth. MCP uses that account connection; the REST API above uses a bearer API key.

MCP connection guide

Replace one document

Use the faxId from create_fax, then call get_faxto find the file's fileId. Call remove_document with both IDs, then attach the updated file with attach_document orattach_document_url. Call get_fax again after processing to review the new file list, page count, and quote before approving a send.

remove_document({ "faxId": "cmr4...", "fileId": "cmr5..." })

Discard the whole draft

Call delete_fax_draft with the faxId to permanently delete an unsent draft and its attachments. Neither deletion tool can change a paid or sent fax.

delete_fax_draft({ "faxId": "cmr4..." })

Prepaid credits

A person adds funds in the developer console. Send calls debit that balance atomically. If funds are low, the API returns the shortfall and a path to add credits.

Agent access

For a direct REST integration, store the API key as a secret in your agent's environment. For MCP, connect each customer through OAuth. After a person adds prepaid credits, either flow can upload a file, review the quote, and send without opening checkout during the fax workflow.

Documentation map

The final docs page can grow from this outline without needing a separate marketing page first.

Authentication Create a fax Upload files Quotes and credits Delivery status