`POST /faxes`

Send a fax

This spends money. Every fax sent is charged to the account.


Scope	`fax:send`
Role permission	TeleConsole → Fax on; Phone numbers — `from` must be one of the role's numbers
Cost	Charged per fax, on the account's plan

The fax is recorded before it is handed over. Every send that passes validation gets an id and is in GET /faxes at once, also when the fax service then refuses it (400 / 502 carry it as error.id; the fax is listed as failed).

201 means handed over, not delivered. The fax goes out over the phone network afterwards, which takes minutes, and a pending fax can still end failed. Poll GET /faxes/{id} until status leaves pending.

Never resend a fax that has an id. Follow it with GET /faxes/{id}; send again only once it is failed (a new fax with a new id).

One recipient per request. To fax several people, make one request each.

from must be a number on the account with fax enabled, among the numbers the credential's user's role allows, and within the key's number grants if it has any. US numbers only, on both ends.

Files are faxed in the order given, after the cover page if you send one. The type is read from each file's content, never its name: PDF, PNG, TIFF, JPEG, GIF, DOC, DOCX, XLS, XLSX, PPT or PPTX. At most 10 MB per file and 200 MB in all, decoded.

Unknown fields are rejected, so a typo like "flies" gets a 400 instead of sending an empty fax.

Request body

Field	Type	Required	Description
`from`	string	yes	One of your account's numbers with fax enabled, that the credential's user's role (and the key's number grants, if any) allows. US number: 10 digits, or 11 starting with `1`; formatting is stripped.
`to`	string	yes	The one recipient. US number: 10 digits, or 11 starting with `1`. There is no list form — one fax, one recipient.
`files`	object[]	no	The documents, faxed in this order. Required unless you send a `cover` — a cover page alone is a valid fax. Each file at most 10 MB, all files together at most 200 MB (decoded sizes).
`files[].name`	string	no	Your own label for the file. Not used to decide its type — that is read from the content.
`files[].data`	string	yes	The file, standard base64. Accepted types, recognized from the content: PDF, PNG, TIFF, JPEG, GIF, DOC, DOCX, XLS, XLSX, PPT, PPTX. Anything else is a `400`. At most 10 MB decoded.
`cover`	object	no	Adds the standard cover page as the first page. Include the object (even empty, `{}`) to send a cover; omit it to send none.
`cover.template`	string	no	Leave this out. Only the standard cover page is supported; naming another template is a `400`.
`cover.name`	string	no	The recipient's name. One line.
`cover.company`	string	no	The recipient's company. One line.
`cover.note`	string	no	A message on the cover page. Line breaks are kept.

One PDF, no cover page:

{
  "from": "12125550188",
  "to": "13475550123",
  "files": [
    {
      "name": "invoice-1042.pdf",
      "data": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK"
    }
  ]
}

A cover page and two documents:

{
  "from": "12125550188",
  "to": "13475550123",
  "cover": {
    "name": "Dr. Rivera",
    "company": "Midtown Clinic",
    "note": "Signed referral attached.\nPlease call us with any questions."
  },
  "files": [
    {
      "name": "referral.pdf",
      "data": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK"
    },
    {
      "name": "insurance-card.png",
      "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
    }
  ]
}

Responses

`201`

Recorded and handed to the fax service — not yet delivered. Almost always pending; it shows failed when the fax service already reported a failure. The Location header points at the new fax; poll it for the result.

Field	Type	Description
`id`	integer	The fax id, for `GET /faxes/{id}`. Always present. A send records the fax before handing it over, so the id exists from the start.
`direction`	`sent` \| `received`
`line`	string	Your fax number the fax went out on (`sent`) or came in to (`received`). Equal to `from` on a sent fax and to `to` on a received one.
`from`	string	Who sent it. On a received fax this is the sender's number as the phone network reported it.
`to`	string	Who it was sent to.
`userId`	integer	The user who sent it — `id` in `GET /users`. For a fax sent through this API, the user the credential acts as. Absent on received faxes.
`pages`	integer	Page count, including the cover page.
`status`	`pending` \| `success` \| `failed`	`pending` — queued or still sending. `success` — delivered. `failed` — not delivered; the reason is in `statusDetail`. A received fax is always `success`.
`statusCode`	integer	Sent faxes only. The fax service's delivery code: `-1` pending, `0` delivered, anything else a failure. Branch on `status`; keep this for logs and support.
`statusDetail`	string	Sent faxes only. The delivery result as text — `queued` while pending, `Success` once delivered, otherwise the failure reason (for example a busy line or no answer). Human-readable; do not parse it.
`createdAt`	string (RFC 3339)	When the fax was sent or received. RFC 3339 UTC.

{
  "data": {
    "id": 7731455,
    "direction": "sent",
    "line": "12125550188",
    "from": "12125550188",
    "to": "13475550123",
    "userId": 481920,
    "pages": 4,
    "status": "pending",
    "statusCode": -1,
    "statusDetail": "queued",
    "createdAt": "2026-10-28T16:20:03Z"
  }
}

Errors

Status	Meaning
`400`	`invalid_request` — a missing or malformed field, a number that is not a US number, an unsupported file type, a file over the size limits, an unknown field, or the fax service refused the fax. Nothing was sent. When the fax service refused it, `error.id` is the fax, listed as `failed`; fix the request before sending again.
`401`	`unauthenticated` — no credential, or one that is invalid, revoked or expired. The `WWW-Authenticate` header names the scope the endpoint wanted.
`403`	`insufficient_scope` (the credential lacks `fax:send`) or `permission_denied` (the credential's user may not send faxes or use `from`, or `from` is not a fax line of this account). Nothing was sent.
`500`	`internal_error` — something failed on our side. For a send, nothing was charged, guaranteed, which is what makes a retry safe.
`502`	`unavailable` — the fax was recorded, but the fax service did not take it. `error.id` is the fax; it is in `GET /faxes` as `failed`, and nothing was sent. Sending again sends a new fax. Without an `id`, nothing was recorded or sent.
`503`	`unavailable` — fax sending is not available. When the message is `fax sending is not configured`, retrying will not help; contact support.

See Errors for the full catalog and what to do about each.

Example

curl -X POST 'https://api.account.telebroad.com/api/public/v1/faxes' \
  -H "Authorization: Bearer $TB_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"from":"12125550188","to":"13475550123","files":[{"name":"invoice-1042.pdf","data":"JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK"}]}'

Try it in the playground →

Request body​

Responses​

201​

Errors​

Example​

Request body

Responses

`201`

Errors

Example