GET /faxes

List sent and received faxes

A page of the account's faxes — sent and received — newest first, for a time window.

Scope	fax:read
Role permission	Fax History not set to Block; Phone numbers — only faxes on the role's numbers
Cost	Free

The window defaults to the last 30 days. end defaults to now and start to 30 days before end; the two may be at most 366 days apart. Both take RFC 3339 or unix seconds. To filter by a fax number, use number.

Every user's faxes on the visible numbers are returned, not only the faxes the credential's own user sent. A key with number grants sees only the granted numbers that its user's role also allows.

A filter on a number the credential cannot see is not an error — it simply matches nothing.

total is returned on the first page (offset=0) only.

Query parameters

Name	Type	Required	Example	Description
number	string	no	12125550188	Only faxes on these fax lines of yours. Comma-separated; US numbers, 10 digits or 11 starting with 1. A value that is not a US number is a 400.
direction	sent | received	no	—	Only sent, or only received, faxes. Omit for both.
user	string	no	481920	Only faxes sent by these users — ids from GET /users, comma-separated. A received fax has no user, so this filter returns sent faxes only.
status	string	no	failed	Comma-separated: success, failed, pending. A received fax is always success.
start	string	no	2026-10-01T00:00:00Z	Start of the window — RFC 3339 or unix seconds. Defaults to 30 days before end.
end	string	no	2026-10-28T00:00:00Z	End of the window — RFC 3339 or unix seconds. Defaults to now.
limit	integer	no	—	Page size. An out-of-range value is a 400 rather than a silent clamp.
offset	integer	no	—

Responses

200

A page of matching faxes.

Field	Type	Description
faxes	object[]	Newest first.
faxes[].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.
faxes[].direction	sent | received
faxes[].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.
faxes[].from	string	Who sent it. On a received fax this is the sender's number as the phone network reported it.
faxes[].to	string	Who it was sent to.
faxes[].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.
faxes[].pages	integer	Page count, including the cover page.
faxes[].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.
faxes[].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.
faxes[].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.
faxes[].createdAt	string (RFC 3339)	When the fax was sent or received. RFC 3339 UTC.
total	integer	How many faxes match across all pages. Returned on the first page (offset=0) only — keep the value from there.
limit	integer	The page size applied.
offset	integer

{
  "data": {
    "faxes": [
      {
        "id": 7731402,
        "direction": "sent",
        "line": "12125550188",
        "from": "12125550188",
        "to": "13475550123",
        "userId": 481920,
        "pages": 3,
        "status": "failed",
        "statusCode": 3,
        "statusDetail": "No answer",
        "createdAt": "2026-10-27T15:02:11Z"
      },
      {
        "id": 7731388,
        "direction": "received",
        "line": "12125550188",
        "from": "17185550142",
        "to": "12125550188",
        "pages": 2,
        "status": "success",
        "createdAt": "2026-10-27T14:40:56Z"
      }
    ],
    "total": 2,
    "limit": 50,
    "offset": 0
  }
}

Errors

Status	Meaning
400	invalid_request — a missing or malformed field, an unknown enum value, or an unknown field in the body. Nothing was charged.
401	unauthenticated — no credential, or one that is invalid, revoked or expired. The WWW-Authenticate header names the scope the endpoint wanted.
403	Two different failures share this status, and the type tells them apart:
500	internal_error — something failed on our side. For a send, nothing was charged, guaranteed, which is what makes a retry safe.

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

Example

curl -X GET 'https://api.account.telebroad.com/api/public/v1/faxes' \
  -H "Authorization: Bearer $TB_KEY"

Try it in the playground →