Faxes

The fax endpoints cover both directions on the account's fax numbers: the history of sent and received faxes, each fax's delivery result and document, and sending a new fax.

Endpoint	Scope	Does
GET /faxes	fax:read	Lists sent and received faxes, newest first, with filters
GET /faxes/{id}	fax:read	Returns one fax and its delivery status. Poll this after a send.
GET /faxes/{id}/file	fax:read	Downloads the fax document, usually a PDF
POST /faxes	fax:send	Sends a fax. Charged.

Reading and sending are separate scopes. A fax is the contents of a communication, like a message or a recording, so reading one needs its own consent. Sending costs money and reaches someone outside the account, so a key that only archives faxes should not be able to send one. Ask for each scope only if you do that thing.

What a key can see and send

A key runs as one of the account's users, picked in the admin center under Integrations → API Keys → Runs as. On the fax endpoints, that user's role decides what the key can do, on top of the key's scopes. An OAuth token works the same way, using the role of the person who authorized it.

To…	The role needs	Role setting
List faxes and check their status	Fax History set to Allow or Allow with View Fax, not Block	Fax History
Download a fax document	Fax History set to Allow with View Fax	Fax History
See a fax number's faxes	The number among the role's Phone Numbers (or all numbers)	Phone Numbers
Send a fax	Fax switched on under TeleConsole, and from among the role's Phone Numbers	TeleConsole → Fax

Within the numbers it can see, a key sees every user's sent and received faxes, not only the ones its own user sent.

A send has one more check: from must be a number on the account with fax enabled. A number the account has released, or one that only does voice or SMS, is refused.

Limiting a key to some fax numbers

A key's Phone numbers grant now covers fax lines as well as texting numbers. Grant a key specific numbers and it can only list, read and send faxes on those numbers. See Resource grants.

A grant can only take away. A key granted a number its user's role does not include still cannot use that number.

:::caution One grant type covers texting, fax and voice numbers The Phone numbers grant is one list. A number in it can be a texting number, a fax line or a voice number, and the same list also limits the caller ID a key may show on calls it places. Granting a key only your fax line also limits its SMS access, and its caller ID, to that line. If one integration needs more than fax, grant every number it uses. :::

When a request is refused

Response	Cause	Fixed by
403 insufficient_scope	The key does not have fax:read or fax:send	Edit the key and add the scope
403 permission_denied on any fax endpoint	The role's Fax History is Block	An admin changes the role
403 permission_denied on /file	Fax History is Allow and not Allow with View Fax	An admin changes the role
403 permission_denied on a send	TeleConsole → Fax is off, from is not among the role's numbers or the key's grants, or from does not have fax enabled	An admin changes the role, the key or the number
An empty list, or 404 on one fax	The fax is on a number the key cannot see	Check the role's Phone Numbers and the key's grants

A fax on a number the key cannot see returns 404, the same as an id that does not exist. The two cases are deliberately indistinguishable.

Status

status	Meaning
pending	Queued or still sending. Sent faxes only.
success	Delivered. A received fax is always success.
failed	Not delivered. statusDetail says why, for example a busy line or no answer.

Sent faxes also carry:

• statusDetail: the result as text. It is queued while pending, Success once delivered, and otherwise the failure reason. It is for people to read, so don't parse it.
• statusCode: the fax service's numeric code. -1 means pending, 0 means delivered, and any other value means failed. Branch on status and keep the code for logs and support tickets.

A send returns 201, almost always with status: pending. That means the fax was recorded and handed to the fax service, not that it was delivered. Delivery happens over the phone network and usually takes a few minutes, and a pending fax can still end failed. Poll GET /faxes/{id} every 30 to 60 seconds until status is no longer pending. Rarely, the 201 already shows failed, when the fax service reported the failure straight away.

The document may not be available yet

For a sent fax, the final document is stored when the fax service reports the result. While the fax is pending, GET /faxes/{id}/file can return 404 with the fax document is not available. Download the document after the status changes to success or failed.

Sending a fax

curl -X POST https://api.account.telebroad.com/api/public/v1/faxes \
  -H "Authorization: Bearer $TB_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "from": "12125550188",
  "to": "13475550123",
  "cover": {
    "name": "Dr. Rivera",
    "company": "Midtown Clinic",
    "note": "Signed referral attached."
  },
  "files": [
    { "name": "referral.pdf", "data": "$(base64 -w0 referral.pdf)" }
  ]
}
EOF

base64 -w0 is GNU coreutils. On macOS use base64 -i referral.pdf.

The response:

{
  "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"
  }
}

The Location header points at /api/public/v1/faxes/7731455. Poll that URL for the result. userId is the user the key runs as.

Limits

Recipients	One per request. To fax several people, make one request for each.
Numbers	US only, on both ends: 10 digits, or 11 digits starting with 1. Spaces, dashes, dots, parentheses and a leading + are stripped.
File types	PDF, PNG, TIFF, JPEG, GIF, DOC, DOCX, XLS, XLSX, PPT, PPTX. The type is detected from the file content, so name can be anything.
Size	At most 10 MB per file and 200 MB in all (decoded).
Encoding	Each file's data is standard base64, not URL-safe base64.
Order	The cover page comes first, then the files in the order you list them.
Cover page	Optional. The standard cover page is the only one available, so leave out template. name and company must be one line of up to 200 characters each. note can be up to 2,000 characters and keeps its line breaks.
Documents	Required unless you send a cover page. A cover page alone is a valid fax.

pages in the response includes the cover page. For a PDF it is the PDF's own page count, and every other file counts as one page.

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

What each response means

A fax that passes validation is recorded before it goes to the fax service. From that moment it has an id and is in GET /faxes, whatever happens next.

Response	The fax
201	Recorded and handed over. Usually pending. Keep the id and poll it.
400 with error.id	The fax service refused it. It is in the list as failed, and nothing was sent. Fix the request before you send again.
502 with error.id	The fax service did not take it. It is in the list as failed, and nothing was sent.
4xx or 5xx without an id	Nothing was recorded and nothing was sent.

{
  "error": {
    "type": "unavailable",
    "message": "the fax server did not accept the fax; it is recorded as failed (see id). Sending it again sends a new fax.",
    "id": 7731456
  }
}

:::danger Sending is charged Every fax sent is charged to the account.

Never resend a fax that has an id. Follow that id with GET /faxes/{id} instead. Send again only once its status is failed. That is a new fax with a new id. :::

Listing faxes with filters

curl -G https://api.account.telebroad.com/api/public/v1/faxes \
  -H "Authorization: Bearer $TB_KEY" \
  --data-urlencode "number=12125550188" \
  --data-urlencode "direction=sent" \
  --data-urlencode "status=failed,pending" \
  --data-urlencode "user=481920" \
  --data-urlencode "start=2026-10-01T00:00:00Z" \
  --data-urlencode "end=2026-10-28T00:00:00Z" \
  --data-urlencode "limit=100"

Parameter	Filters on
number	Your fax lines, comma-separated.
direction	sent or received. Leave it out to get both.
user	The users who sent the fax (ids from GET /users), comma-separated. Received faxes have no user, so this returns sent faxes only.
status	success, failed or pending, comma-separated.
start, end	The time window. RFC 3339 or unix seconds. The default is the last 30 days. The window can be at most 366 days.
limit, offset	Paging. limit defaults to 50, and the maximum is 500.

The response is {"data": {"faxes": […], "total": …, "limit": …, "offset": …}}, newest first. total is only on the first page (offset=0), so save it from there.

To read a whole month of history, keep increasing offset by limit until a page comes back with fewer than limit faxes.

What is not here

• No delete or mark-as-read. Faxes are managed in the portal and TeleConsole.
• No international faxing. A send goes to a US number, from one of your US fax numbers.
• No fax webhooks yet. Poll GET /faxes or GET /faxes/{id}.