> ## Documentation Index
> Fetch the complete documentation index at: https://payperfax.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Check the status

> GET /api/fax/{id}/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](/agents) for the plain-language overview
and [payperfax.com/fax-api/](https://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.

```bash theme={null}
curl https://fax.payperfax.com/api/fax/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/status
```

A sample answer for a delivered fax:

```json theme={null}
{
  "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.

<Note>
  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.
</Note>

## 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](/api/payperfax-openapi.yaml).

## Related

<CardGroup cols={2}>
  <Card title="Send a fax" icon="paper-plane" href="/api/send-a-fax">
    Create call: fields, two answers, errors
  </Card>

  <Card title="Page for AI assistants" icon="robot" href="/agents">
    The rules in plain language
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.