Check the status
GET /api/fax/:id/status: status values, stage, and polling rules.
Endpoint
No authentication.transaction is the id from the create response; status_url in that response is this address in full.
For a fax made from a form link (file_expected), the create response has no id. The person’s confirmation page shows a prompt with the status address; see A fax that still needs a file.
remoteCSID is the station ID that the receiving machine reports. Its owner sets it, so it can be any text or empty. It is not proof of the recipient’s identity.
duration (in seconds) and remoteCSID come from the carrier’s record of the fax. The carrier keeps a record for a delivered fax and for one the destination did not take. Without a record, each is an empty string. remoteCSID is also empty 30 days after the fax ended.
Status values
is_terminal is true.
The stage of a pending fax
While status is pending, stage says where the fax is. It is absent for every other status.
price is {cents, currency, formatted}. It is null, with price_unavailable: true, when no price is configured. The customer cannot pay until it is fixed; this is a fault on our side.
tentative: true means that the pages and the price are not final: the customer can still change the fax before payment.
When documents fail to prepare
A fax whose documents could not be prepared hasstatus: failed, is_terminal: true, is_failed: false, and render_failed (document or machinery). Nothing was sent and nothing was charged.
is_terminal: true is not final. The customer can change the document and submit the same fax again, and the status becomes pending again. After render_failed, read the status again when the customer says the fax was submitted again.When the fax could not be delivered
A fax that could not be delivered has afailure object with a code:
undeliverable: the destination did not accept the fax.failure.reasonsays why:busy,no_answer,number_not_in_use, orother. New values may be added; treat an unknown value asother.error: the fax could not be sent.given_up: the carrier did not report a final result in time. The fax may still have arrived, so do not suggest sending it again without checking with the recipient.
failure.message is English text for people. Do not parse it; use code and reason.
The customer is not charged for a failed fax.
When a fax is expired
Anexpired response has only status, is_terminal, is_failed, and message:
delivered or failed status, also after its documents are deleted.
Errors
An unknownid returns 404 with the JSON body {"message": "Not found."}, also when the request has no Accept header.
A 503 means that the service is briefly unavailable. Read again after the number of seconds in the Retry-After header.
Polling rules
How often to read the status depends on thestage:
is_terminal is true.
OpenAPI
The full field reference and example responses are in the OpenAPI file.Related
Send a fax
Page for AI assistants
Path Parameters
Response
Fax status retrieved successfully
The current status of the fax:
pending: Not finished yet.stagesays where it isdelivered: Fax was successfully received by the destination fax machinefailed: Fax could not be delivered, or its documents could not be prepared (render_failed)expired: The fax is no longer available (messagesays "This fax is no longer available."), or a draft that was never paid has lapsed ("This fax was never sent."). A sent fax keeps itsdeliveredorfailedstatus for ever
pending, delivered, failed, expired Whether the fax has reached a final state. When true, the status
will not change and you can stop polling. Terminal states are:
delivered, failed, and expired. One exception: a fax with
render_failed is terminal, but the customer can change the
document and submit it again; the status is then pending again.
Where a pending fax is. Present only while status is pending:
rendering: the documents are being preparedawaiting_payment: the fax is ready and priced, and the customer has not paid yetsending: paid, and the fax is being sent
rendering, awaiting_payment, sending true when the price could not be computed. Present with ready.
The customer cannot pay until a price is available.
The Called Subscriber Identification (CSID) of the receiving fax
machine, from the same record. This is typically the fax number
or company name configured on the recipient's machine. Empty
string when there is none, and 30 days after the fax ended.
Present in every response but expired.
"IRS TREASURY LINE 03"