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? Read about our MCP server.

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.

1

Create your account

Sign up and verify your email to access the developer console.

2

Fund the account

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

3

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.

  1. 1 POST /api/v1/faxes creates a draft fax job.
  2. 2 POST /api/v1/faxes/{id}/files attaches documents. DELETE an attachment to replace it.
  3. 3 GET /api/v1/faxes/{id} shows file processing and the price.
  4. 4 POST /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..." }
}

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

Store the API key as a secret in your agent's environment. The agent can upload a file, read the quote, and send without opening a checkout during the 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