MCP Server

The Fax.live MCP server allows Claude and other AI clients to call this API on your behalf, sending faxes, tracking delivery, and reviewing billing without a direct integration against the endpoints below.

Read the MCP server documentation →

Response Codes

This API communicates errors using standard HTTP status codes. Each error response also includes a message field describing the specific cause.

Document error codes

A 400 from Upload a document or Send a fax - when a document fails the size/page/format checks described there - also includes a data.errorCode field alongside message, for branching on the failure programmatically instead of matching message text. The same codes appear as validationCode in a successful (non-error) Check document or Check document by URL response:

Check API status

GET /api/v1/status

Confirms your API key is valid and that Fax.live's services are currently up. Useful as a quick check before troubleshooting a failing integration.

curl https://api.fax.live/api/v1/status \
  -H "Authorization: Bearer <publicId>.<secret>"

Response

{
  "status": "ok",
  "checkedAt": "2026-08-14T16:08:53.671Z"
}

Returns 503 with a generic error message if Fax.live is currently unavailable.

Upload a document

POST /api/v1/uploadDocument

Uploads a PDF and returns a fileId you can pass to sendFax below in place of fileUrl - use this instead of hosting the PDF publicly yourself. Uploaded files are automatically deleted after 24 hours.

Request Body

multipart/form-data with a single field:

curl -X POST https://api.fax.live/api/v1/uploadDocument \
  -H "Authorization: Bearer <publicId>.<secret>" \
  -F "file=@document.pdf;type=application/pdf"

Response

{
  "fileId": "b3f1c9e2-4a6d-4b7a-9e21-7c9a6a4d21fe",
  "pageCount": 2,
  "expiresAt": "2026-08-19T16:08:53.671Z"
}

A 400 for a file that fails the size/page/format checks includes a data.errorCode - one of the document error codes:

{
  "statusCode": 400,
  "message": "File exceeds the 250 page limit (312 pages)",
  "data": { "errorCode": "TOO_MANY_PAGES" }
}

Check document

GET /api/v1/checkDocument

Checks a single uploaded file by fileId, or, if omitted, lists all of your currently uploaded files.

Query Parameters

curl "https://api.fax.live/api/v1/checkDocument?fileId=b3f1c9e2-4a6d-4b7a-9e21-7c9a6a4d21fe" \
  -H "Authorization: Bearer <publicId>.<secret>"

Response - checking a single file

estimatedCost fields

{
  "fileId": "b3f1c9e2-4a6d-4b7a-9e21-7c9a6a4d21fe",
  "valid": true,
  "createdAt": "2026-08-19T16:08:53.671Z",
  "expiresAt": "2026-08-20T16:08:53.671Z",
  "pageCount": 3,
  "validToFax": true,
  "validationCode": null,
  "estimatedCost": {
    "pricePerPageCents": 5,
    "currency": "usd",
    "totalCents": 15
  },
  "url": "https://firebasestorage.googleapis.com/..."
}

Returns 404 if no file exists for that fileId.

Response - listing all files

{
  "files": [
    {
      "fileId": "b3f1c9e2-4a6d-4b7a-9e21-7c9a6a4d21fe",
      "valid": true,
      "createdAt": "2026-08-19T16:08:53.671Z",
      "expiresAt": "2026-08-20T16:08:53.671Z",
      "pageCount": 3,
      "validToFax": true,
      "validationCode": null,
      "estimatedCost": {
        "pricePerPageCents": 5,
        "currency": "usd",
        "totalCents": 15
      },
      "url": "https://firebasestorage.googleapis.com/..."
    }
  ]
}

Check document by URL

GET /api/v1/checkDocumentByUrl

Like Check document above, but for a file you haven't uploaded - downloads a publicly reachable PDF from fileUrl and reports the same information, so you can pre-flight-check a fileUrl before passing it to sendFax below.

This endpoint downloads the entire file before it can respond, so it can take up to a couple of minutes for a large file or a slow host - set a generous timeout on your side for this call rather than the fast response times of the other endpoints on this page.

Query Parameters

curl "https://api.fax.live/api/v1/checkDocumentByUrl?fileUrl=https%3A%2F%2Fexample.com%2Fdocument.pdf" \
  -H "Authorization: Bearer <publicId>.<secret>"

Response

estimatedCost fields

{
  "fileUrl": "https://example.com/document.pdf",
  "pageCount": 3,
  "sizeBytes": 482910,
  "validToFax": true,
  "validationError": null,
  "validationCode": null,
  "estimatedCost": {
    "pricePerPageCents": 5,
    "currency": "usd",
    "totalCents": 15
  }
}

Returns 400 if the file couldn't be downloaded at all (e.g. the URL is unreachable or timed out) - that's different from a successful check that reports validToFax: false for a file that downloaded fine but is too large, has too many pages, or isn't a valid PDF:

{
  "fileUrl": "https://example.com/too-many-pages.pdf",
  "pageCount": 312,
  "sizeBytes": 9481022,
  "validToFax": false,
  "validationError": "File exceeds the 250 page limit (312 pages)",
  "validationCode": "TOO_MANY_PAGES",
  "estimatedCost": null
}

Send a fax

POST /api/v1/sendFax

Sends a fax using either a fileId from uploadDocument above or your own publicly hosted PDF via fileUrl. Rejects if a send is already in progress for your account.

This version of the API currently accepts US and Canada destination numbers only, in E.164 format. Numbers from other countries are rejected with a 400 error.

Request Body

Exactly one of fileUrl or fileId is required, along with toNumber:

curl -X POST https://api.fax.live/api/v1/sendFax \
  -H "Authorization: Bearer <publicId>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "toNumber": "+14155551234",
    "fileUrl": "https://example.com/document.pdf"
  }'

Or, sending a previously uploaded document by its fileId instead:

{
  "toNumber": "+14155551234",
  "fileId": "b3f1c9e2-4a6d-4b7a-9e21-7c9a6a4d21fe"
}

Response

{
  "faxId": "fax_abc123",
  "status": "QUEUED"
}

If fileUrl is provided, it's downloaded and validated before sending - a 400 here means nothing was sent, with data.errorCode set to one of the document error codes:

{
  "statusCode": 400,
  "message": "File exceeds the 250 page limit (312 pages)",
  "data": { "errorCode": "TOO_MANY_PAGES" }
}

Check fax status

GET /api/v1/fax/:faxId/status

Returns the full fax entry, including its current status.

Path Parameters

curl https://api.fax.live/api/v1/fax/{faxId}/status \
  -H "Authorization: Bearer <publicId>.<secret>"

Response - Fax Entry

{
  "faxId": "fax_abc123",
  "destination": "+14155551234",
  "origin": "+14155559876",
  "status": "SENT",
  "pageCount": 2,
  "createdAt": "2026-08-14T16:08:53.671Z",
  "completedAt": "2026-08-14T16:09:12.114Z",
  "failReason": null,
  "fileUrl": "https://example.com/document.pdf"
}

Fax history

GET /api/v1/faxHistory

Returns a list of your faxes, newest first. All query parameters are optional.

Query Parameters

curl "https://api.fax.live/api/v1/faxHistory?limit=20&destination=%2B14155551234&startDate=2026-08-01&endDate=2026-08-31" \
  -H "Authorization: Bearer <publicId>.<secret>"

Response

Fax Entry fields

{
  "entries": [
    {
      "faxId": "fax_abc123",
      "destination": "+14155551234",
      "origin": "+14155559876",
      "status": "SENT",
      "pageCount": 2,
      "createdAt": "2026-08-14T16:08:53.671Z",
      "completedAt": "2026-08-14T16:09:12.114Z",
      "failReason": null,
      "fileUrl": "https://example.com/document.pdf"
    }
  ],
  "nextCursor": "fax_xyz789"
}

Billing history

GET /api/v1/billingHistory

Returns your invoices, newest first. All query parameters are optional.

Query Parameters

curl "https://api.fax.live/api/v1/billingHistory?limit=20&startDate=2026-08-01&endDate=2026-08-31" \
  -H "Authorization: Bearer <publicId>.<secret>"

Response

Billing Entry fields

{
  "entries": [
    {
      "id": "in_1AbCdEfGhIjKlMnO",
      "status": "paid",
      "total": 1999,
      "currency": "USD",
      "created": "2026-08-14T16:08:53.671Z",
      "description": "Fax API Access",
      "hostedInvoiceUrl": "https://api.fax.live/api/v1/billingHistory/in_1AbCdEfGhIjKlMnO/hosted",
      "invoicePdf": "https://pay.fax.live/invoice/.../pdf"
    }
  ],
  "nextCursor": "in_0ZyXwVuTsRqPoNm"
}

Balance

GET /api/v1/balance

Returns your current account balance information.

curl https://api.fax.live/api/v1/balance \
  -H "Authorization: Bearer <publicId>.<secret>"

Response

{
  "faxCreditUsage": {
    "balanceCents": 350,
    "creditsUsed": 7
  },
  "baseFee": {
    "priceCents": 199,
    "term": "MONTH"
  },
  "nextBillingDate": "2026-09-14T16:08:53.671Z",
  "totalCents": 549,
  "paymentMethodOnFile": true,
  "cardExpired": false,
  "manageBillingUrl": "https://api.fax.live/billing"
}