Skip to main content
Get fax delivery status
Poll the status endpoint to follow a fax from creation to delivery or failure. See the page for AI assistants for the plain-language overview and payperfax.com/pay-per-fax-api/ for the main site.

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.
Example response for a delivered fax:
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

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. 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 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 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 a failure object with a code:
  • undeliverable: the destination did not accept the fax. failure.reason says why: busy, no_answer, number_not_in_use, or other. New values may be added; treat an unknown value as other.
  • 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

An expired response has only status, is_terminal, is_failed, and message: A sent fax keeps its delivered or failed status, also after its documents are deleted.

Errors

An unknown id 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 the stage: Stop when is_terminal is true.

OpenAPI

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

Send a fax

The create request: fields, the two kinds of response, errors

Page for AI assistants

The rules in plain language

Path Parameters

transaction
string<uuid>
required

The id from the create response. It is also in the status address of the tracking prompt on the confirmation page.

Example:

"9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"

Response

Fax status retrieved successfully

status
enum<string>
required

The current status of the fax:

  • pending: Not finished yet. stage says where it is
  • delivered: Fax was successfully received by the destination fax machine
  • failed: Fax could not be delivered, or its documents could not be prepared (render_failed)
  • expired: The fax is no longer available (message says "This fax is no longer available."), or a draft that was never paid has lapsed ("This fax was never sent."). A sent fax keeps its delivered or failed status for ever
Available options:
pending,
delivered,
failed,
expired
is_terminal
boolean
required

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.

is_failed
boolean
required

Whether the fax failed to deliver. true when the status is failed and the fax was not delivered (a failure object is present). false for a fax with render_failed: its status is failed, but nothing was sent.

stage
enum<string>

Where a pending fax is. Present only while status is pending:

  • rendering: the documents are being prepared
  • awaiting_payment: the fax is ready and priced, and the customer has not paid yet
  • sending: paid, and the fax is being sent
Available options:
rendering,
awaiting_payment,
sending
delayed
boolean

Present only while stage is sending. true once the customer was told that there is no final result yet: the result may then take hours. Read the status every few minutes instead of every 15 seconds.

processing
boolean

true while the documents of an unpaid fax are being prepared.

ready
boolean

true when an unpaid fax is prepared and priced. pages and price come with it.

pages
integer

The number of pages of the prepared fax. Present with ready.

Required range: x >= 1
Example:

3

price
object | null

The price of the prepared fax. Present with ready. Null when no price is configured for the currency (see price_unavailable).

price_unavailable
boolean

true when the price could not be computed. Present with ready. The customer cannot pay until a price is available.

tentative
boolean

true when pages and price are not final: the customer can still change the fax before payment. Present with ready.

render_failed
enum<string>

Present when the documents of an unpaid fax could not be prepared. The status is then failed, with is_failed false: nothing was sent and nothing was charged. The customer can change the document and submit the same fax again.

Available options:
document,
machinery
duration
string

The transmission time in seconds, 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. Empty string until there is a record, and for a fax that has none. Present in every response but expired.

Example:

"85"

remoteCSID
string

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.

Example:

"IRS TREASURY LINE 03"

submitted_at
string<date-time> | null

ISO 8601 timestamp of when the fax was submitted to the carrier for transmission. Null if the fax hasn't been submitted yet. Present once the fax is paid.

Example:

"2025-12-21T16:06:38+00:00"

completed_at
string<date-time> | null

ISO 8601 timestamp of when the fax transmission completed (successfully or unsuccessfully). Null while the fax is still in progress. Present once the fax is paid.

Example:

"2025-12-21T16:08:03+00:00"

pages_sent
integer | null

The number of pages successfully transmitted. For a successful delivery, this should match the total pages in the document. Null until the carrier reports it. May be 0 if the fax failed before any pages were sent. Present once the fax is paid.

Required range: x >= 0
Example:

2

failure
object

Details about why a fax failed to deliver. Only present when is_failed is true.

message
string

Present only when status is expired: "This fax is no longer available." or "This fax was never sent." (a draft that was never paid).

Example:

"This fax is no longer available."