Check the status

GET /api/fax//status: status values, stage, and polling rules.

Poll the status endpoint to follow a fax from submission to delivery or failure.

See the page for AI assistants for the plain-language overview and payperfax.com/fax-api/ for the main site.

Endpoint

GET https://fax.payperfax.com/api/fax/{transaction}/status

No authentication. The transaction is the id from the create call.

curl https://fax.payperfax.com/api/fax/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/status

A sample answer for a delivered fax:

{
  "status": "delivered",
  "is_terminal": true,
  "is_failed": false,
  "duration": "85",
  "remoteCSID": "IRS TREASURY LINE 03",
  "submitted_at": "2025-12-21T16:06:38+00:00",
  "completed_at": "2025-12-21T16:08:03+00:00",
  "pages_sent": 2
}

Status values

Status	Terminal	Description
pending	No	Not finished yet. stage says where it is
delivered	Yes	Successfully received by the destination
failed	Yes	Could not be delivered, or its documents could not be prepared
expired	Yes	Data deleted after 30 days, or a draft that was never paid and has lapsed

Stop polling when 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.

stage	Meaning	Other fields
rendering	The documents are being prepared	processing: true
awaiting_payment	The fax is ready and priced. The customer has not paid yet	ready: true, pages, price, price_unavailable, tentative: true
sending	Paid. The fax is being sent	submitted_at once it is at the carrier

price is {cents, currency, formatted}. It is null, with price_unavailable: true, when no price is configured. The customer then cannot pay yet; 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 has status: failed, is_terminal: true, is_failed: false and render_failed (document or machinery). Nothing was sent and nothing was charged.

This is the one case where is_terminal: true is not the end. The customer can change the document and submit the same fax again. The status is then 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 a failure object:

• code: "undeliverable" - the destination did not take the fax (busy, no answer, not a fax machine).
• code: "error" - the fax could not be sent.
• code: "given_up" - no final answer from the carrier in time.

The customer is not charged for a failed fax.

An unknown id gives a 404 with the JSON body {"message": "Not found."}, also when the request has no Accept header.

Polling rules

How often to read the status depends on the stage:

stage	What to do
rendering	Read again after a few seconds. It usually takes less than a minute
awaiting_payment	Do not poll. A person must pay, and a draft is kept for 4 hours. Read again when the person says that the payment is done
sending	Read every 15 seconds. A typical delivery takes 1 to 2 minutes per page

Stop when is_terminal is true.

OpenAPI

The full field reference and example answers are in the OpenAPI file.

Related

Send a fax

Create call: fields, two answers, errors

Page for AI assistants

The rules in plain language