# One-time send API reference

> The one-time send operations of the Fax for Agents API. Create an order for one fax, open its card payment, confirm it by mailed link and read the receipt.

Page: https://faxforagents.com/docs/api/reference/one-time-sends/
Last changed: 2026-11-13

Updated Nov 13, 2026

11 operations of the Fax for Agents API, from the OpenAPI document version 1.20.0, snapshot of 2026-11-13. The base URL is `https://api.faxforagents.com/v1`. This is one group of the [full reference](https://faxforagents.com/docs/api/reference/).

- Creating a one-time order charges nothing and sends nothing.
- The card of a one-time order is authorized at checkout and charged when the carrier confirms delivery.
- The confirmation link of a one-time order works once, and a repeat by anyone else answers 409 link_used.

## Operations

- `GET /v1/one-time-sends` List the organization's one-time orders, newest first
- `POST /v1/one-time-sends` Create a one-time order: one document to one fax number, priced from the card
- `POST /v1/one-time-sends/by-token` What a confirmation link is for, without using it
- `GET /v1/one-time-sends/by-token/{token}` What a confirmation link is for, without using it (token in the path)
- `GET /v1/one-time-sends/config` Whether one-time sends are open here, and the card and limits an order is priced and checked by
- `POST /v1/one-time-sends/from-quote` Create a one-time order from a live quote the wallet does not cover
- `GET /v1/one-time-sends/{one_time_order_id}` Read a one-time order: where it stands, what to do next, and the fax with its evidence
- `POST /v1/one-time-sends/{one_time_order_id}/checkout` Open the card payment of a one-time order
- `POST /v1/one-time-sends/{one_time_order_id}/confirm` Confirm a one-time order with the token of the mailed link: the fax is released
- `GET /v1/one-time-sends/{one_time_order_id}/receipt.pdf` The receipt of a one-time order's fax as a one-page PDF
- `POST /v1/one-time-sends/{one_time_order_id}/resend-confirmation` Mail the confirmation link of a one-time order again

## What is a one-time order?

One document to one fax number, paid by card. There is no wallet behind it and no top-up before it. The order moves through four steps: create, pay, confirm, send. Each step is one operation in this group, and the read of the order says which step comes next in `next`.

`GET /v1/one-time-sends/config` says whether one-time sends are open, and returns the card and the limits an order is priced and checked by. It takes no credential.

## Who can create an order?

Anyone. `POST /v1/one-time-sends` needs no credential, as its description states. The body carries the text of the document, the destination in `to` and a `sender_name` for the cover sheet. `accept_aup` records that the sender accepts the acceptable use policy. Without a credential it also needs an `email`, where the confirmation link and the receipt go.

The answer carries the price, the page count and the status token. Nothing is charged and nothing is sent by this call. A live key with `fax:send`, or a signed-in session, may create an order for its organization in the same way.

## What is the status token?

The credential of a person who has no account. Four operations accept it next to a key or a session: the read of the order, the checkout, the receipt and the resend. It travels as the header `X-FFA-Order-Token` or as `?t=` in the address. It opens that one order and nothing else.

## How is the order paid?

`POST /v1/one-time-sends/{one_time_order_id}/checkout` answers the hosted payment page of the order. The card is authorized there, not charged. It is charged when the carrier confirms delivery. A second call answers the same page while it can still be paid, and a new one after it expired.

An order whose `aup_accepted` is false needs `{"accept_aup": true}` in the body once, from the status token or a session. The person who pays accepts the policy, never a key.

## Why does a mailed link release the fax?

Because it proves the sender's address. After the payment a confirmation link goes to the order's email. `POST /v1/one-time-sends/{one_time_order_id}/confirm` takes the token of that link and releases the fax. The link works once. A repeat by the same signed-in person answers the confirmed order again. Any other repeat answers 409 `link_used` and sends nothing.

`POST /v1/one-time-sends/by-token` lets the confirm page show what the link is for before the click. It reads and consumes nothing, and the token travels in the body so it stays out of the address. An older route with the token in the path is kept for pages loaded before 2026-11-12.

`POST /v1/one-time-sends/{one_time_order_id}/resend-confirmation` mails the link again, at most three times per order and once in ten minutes. Earlier links keep working.

## Can an API key use a quote here?

Yes. `POST /v1/one-time-sends/from-quote` creates an order from a live quote the wallet does not cover. The quote supplies the document, the destination and the cover. The price is the card's one-time price, not the quote's. An API key needs what a wallet send of the quote needs: an `approval_id`, or a delegated policy that allows the send. Paying by card replaces neither. Without one the answer is 403 `approval_required`.

## How do I read the outcome?

`GET /v1/one-time-sends/{one_time_order_id}` returns where the order stands, what to do next and the fax with its evidence. `GET /v1/one-time-sends/{one_time_order_id}/receipt.pdf` is the delivery receipt as a one-page PDF. It says charged only once the payment provider confirmed the capture, and it answers 409 while the fax has not ended. `GET /v1/one-time-sends` lists an organization's orders, newest first, with `fax:read`.

## Each operation in detail

### GET `/v1/one-time-sends`

List the organization's one-time orders, newest first

Credential: an API key or a signed-in session. Scope: `fax:read`.

#### Parameters

GET /v1/one-time-sends parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `cursor` | query | string or null | no |  |
| `limit` | query | integer | no | Default `50` . |
| `status` | query | string (draft, checkout_open, authorized, awaiting_confirmation, released, capturing, canceling, captured, released_hold, expired, refused, settle_failed) or null | no |  |

#### Responses

GET /v1/one-time-sends responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |

#### Response fields

GET /v1/one-time-sends response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object OneTimeOrder | yes |  |
| `next_cursor` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/one-time-sends \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/one-time-sends`

Create a one-time order: one document to one fax number, priced from the card

No credential is needed. The answer carries the price, the page count and the status token; the next step is the checkout. A live key with fax:send or a signed-in session may create an order for its organization. Nothing is charged and nothing is sent by this call.

Credential: an API key or a signed-in session. Works without one too. Scope: `fax:send`.

#### Parameters

POST /v1/one-time-sends parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | no | Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay. |

#### Request body application/json, required

The JSON form of an order: text only. A file (PDF, PNG, JPEG, TIFF) goes as ``multipart/form-data`` with the same field names and the part ``file``.

POST /v1/one-time-sends request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accept_aup` | boolean | yes | True: the sender accepts the acceptable use policy and the terms the config route names. |
| `delete_after_send` | boolean | no | Delete the document and the transmitted copy the moment the fax ends in delivered, partial or failed. The order, the receipt and the carrier evidence stay; they hold no document content. A fax that ends unknown keeps the document until the carrier reports, or until the retention period ends. Default: keep the document for the retention period. |
| `email` | string or null | no | Where the confirmation link, the receipt and the evidence go. Required without a credential; a signed-in session uses its own address; a key may leave it out to use the organization's. |
| `message` | string or null | no |  |
| `sender_name` | string | yes | Printed on the cover sheet. 2 to 120 characters. |
| `source_ref` | string or null | no | Where the sender came from (a short tag, never a URL). |
| `subject` | string or null | no |  |
| `text` | string | yes | The document as plain text or Markdown. |
| `text_format` | string (text, markdown) | no |  |
| `to` | string | yes | The destination fax number, E.164. |
| `to_name` | string or null | no |  |

#### Request body multipart/form-data, required

The JSON form of an order: text only. A file (PDF, PNG, JPEG, TIFF) goes as ``multipart/form-data`` with the same field names and the part ``file``.

POST /v1/one-time-sends request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accept_aup` | boolean | yes | True: the sender accepts the acceptable use policy and the terms the config route names. |
| `delete_after_send` | boolean | no | Delete the document and the transmitted copy the moment the fax ends in delivered, partial or failed. The order, the receipt and the carrier evidence stay; they hold no document content. A fax that ends unknown keeps the document until the carrier reports, or until the retention period ends. Default: keep the document for the retention period. |
| `email` | string or null | no | Where the confirmation link, the receipt and the evidence go. Required without a credential; a signed-in session uses its own address; a key may leave it out to use the organization's. |
| `file` | string (binary) | no | The document: PDF, PNG, JPEG or TIFF. Send this or text, not both. |
| `message` | string or null | no |  |
| `sender_name` | string | yes | Printed on the cover sheet. 2 to 120 characters. |
| `source_ref` | string or null | no | Where the sender came from (a short tag, never a URL). |
| `subject` | string or null | no |  |
| `text` | string | no | The document as plain text or Markdown. |
| `text_format` | string (text, markdown) | no |  |
| `to` | string | yes | The destination fax number, E.164. |
| `to_name` | string or null | no |  |

#### Responses

POST /v1/one-time-sends responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `404` | not_found: no such resource for this credential. A resource of another organization answers the same. |
| `409` | The resource is in a state that refuses the call, or the Idempotency-Key was used with a different request (idempotency_key_conflict). error.code names the state. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |
| `503` | Something this call depends on is not available or not set up here, for example billing_unavailable or provider_unavailable. error.retryable says whether to send the same call again. |

#### Response fields

POST /v1/one-time-sends response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `aup_accepted` | boolean | no | Whether a person accepted the acceptable use policy and the terms for this order. False for an order a key created until the payer accepts on the order's page; the checkout needs it. |
| `aup_version` | string | yes |  |
| `authorized_at` | string or null | yes |  |
| `capture_deadline_at` | string or null | yes |  |
| `captured_micro` | integer | yes |  |
| `card` | object OneTimeCard or null | yes |  |
| `checkout_expires_at` | string or null | yes |  |
| `checkout_url` | string or null | yes |  |
| `confirm_deadline_at` | string or null | yes |  |
| `confirm_mail_sent_at` | string or null | yes |  |
| `cover` | object or null | yes |  |
| `created_at` | string | yes |  |
| `delete_after_send` | boolean | no | The sender asked for the document and the transmitted copy to be deleted the moment the fax ends in delivered, partial or failed. |
| `document_deleted` | boolean | no | True once no copy of the document is held: it was deleted after the send, by the retention period or by its owner, or the order ended before it was released and the uploaded file was removed. The order, the fax and the carrier evidence stay; they hold no document content. |
| `document_expires_at` | string or null | no | When the retention period deletes the stored document. Null before the release and once the document is deleted. |
| `document_id` | string or null | yes |  |
| `document_pages` | integer | yes |  |
| `document_sha256` | string | yes |  |
| `email` | string | yes |  |
| `email_verified` | boolean | yes |  |
| `environment` | string (live, test) | yes |  |
| `failure_code` | string or null | yes |  |
| `fax` | object or null | no | The fax job (the FaxJob shape) once the order was released; null before. |
| `fax_job_id` | string or null | yes |  |
| `id` | string | yes |  |
| `next` | string (checkout, confirm, wait, done) | yes |  |
| `price` | object OneTimePrice | yes |  |
| `queue` | object OneTimeQueue or null | no | The wait for a carrier line while the order has not ended and its fax is not on a line yet. Null for an ended order, a fax that is sending, and a test order. |
| `quote_id` | string or null | yes |  |
| `refunded_micro` | integer | no | What was refunded to the card after the charge, in micro-units, as the ledger holds it. Zero when nothing was refunded. captured_micro stays what was charged. |
| `released_at` | string or null | yes |  |
| `resend_allowed_at` | string or null | no | When the confirmation mail may be asked for again; null when it may not. |
| `route` | string | yes |  |
| `sender_name` | string | yes |  |
| `settled_at` | string or null | yes |  |
| `source` | string (web, api, mcp) | yes |  |
| `status` | string (draft, checkout_open, authorized, awaiting_confirmation, released, capturing, canceling, captured, released_hold, expired, refused, settle_failed) | yes |  |
| `status_token` | string | yes |  |
| `status_url` | string | yes |  |
| `to` | string | yes |  |
| `updated_at` | string | yes |  |
| `warnings` | array of object | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/one-time-sends \ -X POST \ -H "Content-Type: application/json" \ -d '{"sender_name":"example","to":"+15550000001","accept_aup":false,"text":"example"}'`
```

### POST `/v1/one-time-sends/by-token`

What a confirmation link is for, without using it

The confirm page reads this before the click, with the token in the body. Nothing is consumed by reading it, and nothing is changed: the call is a read that keeps the token out of the address. Idempotency-Key is accepted but ignored.

Credential: none.

#### Request body application/json, required

POST /v1/one-time-sends/by-token request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | yes | The token of the link in the confirmation mail. |

#### Responses

POST /v1/one-time-sends/by-token responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `404` | not_found: no such resource for this credential. A resource of another organization answers the same. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |

#### Response fields

POST /v1/one-time-sends/by-token response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `confirm_deadline_at` | string or null | yes |  |
| `currency` | string | yes |  |
| `document_pages` | integer | yes |  |
| `email` | string | yes |  |
| `order_id` | string | yes |  |
| `sender_name` | string | yes |  |
| `state` | string (ok, link_used, link_expired) | yes |  |
| `status` | string (draft, checkout_open, authorized, awaiting_confirmation, released, capturing, canceling, captured, released_hold, expired, refused, settle_failed) | yes |  |
| `to` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/one-time-sends/by-token \ -X POST \ -H "Content-Type: application/json" \ -d '{"token":"example"}'`
```

### GET `/v1/one-time-sends/by-token/{token}`

What a confirmation link is for, without using it (token in the path)

Kept for pages loaded before 2026-11-12. The token in a path reaches access logs, so new callers post it to /v1/one-time-sends/by-token instead. Nothing is consumed by reading it.

Credential: none.

#### Parameters

GET /v1/one-time-sends/by-token/{token} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `token` | path | string | yes |  |

#### Responses

GET /v1/one-time-sends/by-token/{token} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `404` | not_found: no such resource for this credential. A resource of another organization answers the same. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |

#### Response fields

GET /v1/one-time-sends/by-token/{token} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `confirm_deadline_at` | string or null | yes |  |
| `currency` | string | yes |  |
| `document_pages` | integer | yes |  |
| `email` | string | yes |  |
| `order_id` | string | yes |  |
| `sender_name` | string | yes |  |
| `state` | string (ok, link_used, link_expired) | yes |  |
| `status` | string (draft, checkout_open, authorized, awaiting_confirmation, released, capturing, canceling, captured, released_hold, expired, refused, settle_failed) | yes |  |
| `to` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/one-time-sends/by-token/TOKEN`
```

### GET `/v1/one-time-sends/config`

Whether one-time sends are open here, and the card and limits an order is priced and checked by

Credential: none.

#### Responses

GET /v1/one-time-sends/config responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |

#### Response fields

GET /v1/one-time-sends/config response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `aup_url` | string | yes |  |
| `aup_version` | string | yes |  |
| `currency` | string | yes |  |
| `effective_from` | string | yes |  |
| `enabled` | boolean | yes |  |
| `formats` | array of string | yes |  |
| `max_document_pages` | integer | yes |  |
| `max_text_chars` | integer | yes |  |
| `max_upload_bytes` | integer | yes |  |
| `price_version` | string | yes |  |
| `queue` | object OneTimeQueue or null | no | The wait a fax ordered now would face for a carrier line. Null when one-time sends are closed here or the carrier has no line limit. |
| `reason` | string or null | no |  |
| `routes` | object | yes |  |
| `terms_url` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/one-time-sends/config`
```

### POST `/v1/one-time-sends/from-quote`

Create a one-time order from a live quote the wallet does not cover

The quote supplies the document, the destination and the cover; the price is the card's one-time price, not the quote's. The quote then belongs to the order. Needs a live key with fax:send. A key needs what a wallet send of the quote needs: approval_id, or a delegated policy that allows the send. Paying by card replaces neither; without one the answer is 403 approval_required.

Credential: an API key or a signed-in session. Scope: `fax:send`.

#### Parameters

POST /v1/one-time-sends/from-quote parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | no | Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay. |

#### Request body application/json, required

POST /v1/one-time-sends/from-quote request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accept_aup` | boolean | no | A session sends true: the signed-in person accepts the acceptable use policy and the terms. A key's value is not recorded: the person who pays accepts on the order's page. |
| `approval_id` | string or null | no | An approved, unused approval request for this quote (POST /v1/approval-requests). A key needs it unless a delegated policy allows the send. A session needs none. |
| `delete_after_send` | boolean or null | no | Delete the document and the transmitted copy the moment the fax ends in delivered, partial or failed. The order, the receipt and the carrier evidence stay; they hold no document content. A fax that ends unknown keeps the document until the carrier reports, or until the retention period ends. Left out, the quote's own delete_after_send applies. |
| `email` | string or null | no |  |
| `quote_id` | string | yes |  |
| `sender_name` | string | yes | Printed on the cover sheet. 2 to 120 characters. |
| `source_ref` | string or null | no |  |

#### Responses

POST /v1/one-time-sends/from-quote responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `404` | not_found: no such resource for this credential. A resource of another organization answers the same. |
| `409` | The resource is in a state that refuses the call, or the Idempotency-Key was used with a different request (idempotency_key_conflict). error.code names the state. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |
| `503` | Something this call depends on is not available or not set up here, for example billing_unavailable or provider_unavailable. error.retryable says whether to send the same call again. |

#### Response fields

POST /v1/one-time-sends/from-quote response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `aup_accepted` | boolean | no | Whether a person accepted the acceptable use policy and the terms for this order. False for an order a key created until the payer accepts on the order's page; the checkout needs it. |
| `aup_version` | string | yes |  |
| `authorized_at` | string or null | yes |  |
| `capture_deadline_at` | string or null | yes |  |
| `captured_micro` | integer | yes |  |
| `card` | object OneTimeCard or null | yes |  |
| `checkout_expires_at` | string or null | yes |  |
| `checkout_url` | string or null | yes |  |
| `confirm_deadline_at` | string or null | yes |  |
| `confirm_mail_sent_at` | string or null | yes |  |
| `cover` | object or null | yes |  |
| `created_at` | string | yes |  |
| `delete_after_send` | boolean | no | The sender asked for the document and the transmitted copy to be deleted the moment the fax ends in delivered, partial or failed. |
| `document_deleted` | boolean | no | True once no copy of the document is held: it was deleted after the send, by the retention period or by its owner, or the order ended before it was released and the uploaded file was removed. The order, the fax and the carrier evidence stay; they hold no document content. |
| `document_expires_at` | string or null | no | When the retention period deletes the stored document. Null before the release and once the document is deleted. |
| `document_id` | string or null | yes |  |
| `document_pages` | integer | yes |  |
| `document_sha256` | string | yes |  |
| `email` | string | yes |  |
| `email_verified` | boolean | yes |  |
| `environment` | string (live, test) | yes |  |
| `failure_code` | string or null | yes |  |
| `fax` | object or null | no | The fax job (the FaxJob shape) once the order was released; null before. |
| `fax_job_id` | string or null | yes |  |
| `id` | string | yes |  |
| `next` | string (checkout, confirm, wait, done) | yes |  |
| `price` | object OneTimePrice | yes |  |
| `queue` | object OneTimeQueue or null | no | The wait for a carrier line while the order has not ended and its fax is not on a line yet. Null for an ended order, a fax that is sending, and a test order. |
| `quote_id` | string or null | yes |  |
| `refunded_micro` | integer | no | What was refunded to the card after the charge, in micro-units, as the ledger holds it. Zero when nothing was refunded. captured_micro stays what was charged. |
| `released_at` | string or null | yes |  |
| `resend_allowed_at` | string or null | no | When the confirmation mail may be asked for again; null when it may not. |
| `route` | string | yes |  |
| `sender_name` | string | yes |  |
| `settled_at` | string or null | yes |  |
| `source` | string (web, api, mcp) | yes |  |
| `status` | string (draft, checkout_open, authorized, awaiting_confirmation, released, capturing, canceling, captured, released_hold, expired, refused, settle_failed) | yes |  |
| `status_token` | string | yes |  |
| `status_url` | string | yes |  |
| `to` | string | yes |  |
| `updated_at` | string | yes |  |
| `warnings` | array of object | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/one-time-sends/from-quote \ -X POST \ -H "Authorization: Bearer ffa_test_..." \ -H "Content-Type: application/json" \ -d '{"quote_id":"quote_example","sender_name":"example"}'`
```

### GET `/v1/one-time-sends/{one_time_order_id}`

Read a one-time order: where it stands, what to do next, and the fax with its evidence

Credential: an API key, a signed-in session or the status token of the order. Scope: `fax:read`.

#### Parameters

GET /v1/one-time-sends/{one_time_order_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `one_time_order_id` | path | string | yes |  |
| `t` | query | string or null | no | The status token, when no header carries it. |
| `X-FFA-Order-Token` | header | string | no | The status token of the order, for a caller without a key or a session. |

#### Responses

GET /v1/one-time-sends/{one_time_order_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `404` | not_found: no such resource for this credential. A resource of another organization answers the same. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |

#### Response fields

GET /v1/one-time-sends/{one_time_order_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `aup_accepted` | boolean | no | Whether a person accepted the acceptable use policy and the terms for this order. False for an order a key created until the payer accepts on the order's page; the checkout needs it. |
| `aup_version` | string | yes |  |
| `authorized_at` | string or null | yes |  |
| `capture_deadline_at` | string or null | yes |  |
| `captured_micro` | integer | yes |  |
| `card` | object OneTimeCard or null | yes |  |
| `checkout_expires_at` | string or null | yes |  |
| `checkout_url` | string or null | yes |  |
| `confirm_deadline_at` | string or null | yes |  |
| `confirm_mail_sent_at` | string or null | yes |  |
| `cover` | object or null | yes |  |
| `created_at` | string | yes |  |
| `delete_after_send` | boolean | no | The sender asked for the document and the transmitted copy to be deleted the moment the fax ends in delivered, partial or failed. |
| `document_deleted` | boolean | no | True once no copy of the document is held: it was deleted after the send, by the retention period or by its owner, or the order ended before it was released and the uploaded file was removed. The order, the fax and the carrier evidence stay; they hold no document content. |
| `document_expires_at` | string or null | no | When the retention period deletes the stored document. Null before the release and once the document is deleted. |
| `document_id` | string or null | yes |  |
| `document_pages` | integer | yes |  |
| `document_sha256` | string | yes |  |
| `email` | string | yes |  |
| `email_verified` | boolean | yes |  |
| `environment` | string (live, test) | yes |  |
| `failure_code` | string or null | yes |  |
| `fax` | object or null | no | The fax job (the FaxJob shape) once the order was released; null before. |
| `fax_job_id` | string or null | yes |  |
| `id` | string | yes |  |
| `next` | string (checkout, confirm, wait, done) | yes |  |
| `price` | object OneTimePrice | yes |  |
| `queue` | object OneTimeQueue or null | no | The wait for a carrier line while the order has not ended and its fax is not on a line yet. Null for an ended order, a fax that is sending, and a test order. |
| `quote_id` | string or null | yes |  |
| `refunded_micro` | integer | no | What was refunded to the card after the charge, in micro-units, as the ledger holds it. Zero when nothing was refunded. captured_micro stays what was charged. |
| `released_at` | string or null | yes |  |
| `resend_allowed_at` | string or null | no | When the confirmation mail may be asked for again; null when it may not. |
| `route` | string | yes |  |
| `sender_name` | string | yes |  |
| `settled_at` | string or null | yes |  |
| `source` | string (web, api, mcp) | yes |  |
| `status` | string (draft, checkout_open, authorized, awaiting_confirmation, released, capturing, canceling, captured, released_hold, expired, refused, settle_failed) | yes |  |
| `status_url` | string or null | no | The order's page for the person who pays or confirms, with a fresh status token. Present on a read by a key or session of the order's organization while the order is not done. |
| `to` | string | yes |  |
| `updated_at` | string | yes |  |
| `warnings` | array of object | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/one-time-sends/ONE_TIME_ORDER_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/one-time-sends/{one_time_order_id}/checkout`

Open the card payment of a one-time order

Answers the hosted payment page of the order. The card is authorized there, not charged: it is charged when the carrier confirms delivery. A second call answers the same page while it can still be paid, and a new one after it expired. An order whose aup_accepted is false needs {"accept_aup": true} in the body once, from the status token or a session: the person who pays accepts the policy, never a key.

Credential: an API key, a signed-in session or the status token of the order. Scope: `fax:send`.

#### Parameters

POST /v1/one-time-sends/{one_time_order_id}/checkout parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `one_time_order_id` | path | string | yes |  |
| `t` | query | string or null | no | The status token, when no header carries it. |
| `Idempotency-Key` | header | string | no | Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay. |
| `X-FFA-Order-Token` | header | string | no | The status token of the order, for a caller without a key or a session. |

#### Request body application/json

POST /v1/one-time-sends/{one_time_order_id}/checkout request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accept_aup` | boolean | no | True: the person who pays accepts the acceptable use policy and the terms. Needed once, for an order whose aup_accepted is false, and taken only from the status token or a session. |

#### Responses

POST /v1/one-time-sends/{one_time_order_id}/checkout responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `402` | The prepaid balance does not cover the call: insufficient_balance. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `404` | not_found: no such resource for this credential. A resource of another organization answers the same. |
| `409` | The resource is in a state that refuses the call, or the Idempotency-Key was used with a different request (idempotency_key_conflict). error.code names the state. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |
| `503` | Something this call depends on is not available or not set up here, for example billing_unavailable or provider_unavailable. error.retryable says whether to send the same call again. |

#### Response fields

POST /v1/one-time-sends/{one_time_order_id}/checkout response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `checkout_url` | string | yes |  |
| `currency` | string | yes |  |
| `expires_at` | string | yes |  |
| `order_id` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/one-time-sends/ONE_TIME_ORDER_ID/checkout \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/one-time-sends/{one_time_order_id}/confirm`

Confirm a one-time order with the token of the mailed link: the fax is released

Proves the sender's address and releases the fax. In a browser without a session it also signs the payer in and sets the session cookies. Idempotency-Key is accepted but ignored: the link works once. A repeat by the same signed-in person answers the confirmed order again; any other repeat answers 409 link_used and sends nothing.

Credential: none.

#### Parameters

POST /v1/one-time-sends/{one_time_order_id}/confirm parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `one_time_order_id` | path | string | yes |  |

#### Request body application/json, required

POST /v1/one-time-sends/{one_time_order_id}/confirm request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | yes | The token of the link in the confirmation mail. |

#### Responses

POST /v1/one-time-sends/{one_time_order_id}/confirm responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `404` | not_found: no such resource for this credential. A resource of another organization answers the same. |
| `409` | The resource is in a state that refuses the call, or the Idempotency-Key was used with a different request (idempotency_key_conflict). error.code names the state. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |
| `503` | Something this call depends on is not available or not set up here, for example billing_unavailable or provider_unavailable. error.retryable says whether to send the same call again. |

#### Response fields

POST /v1/one-time-sends/{one_time_order_id}/confirm response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `me` | object or null | no |  |
| `order` | object OneTimeOrder | yes | One order of the one-time send. ``next`` is what the caller does now: ``checkout`` (open the payment), ``confirm`` (the payer clicks the link in the mail), ``wait`` (nothing to do; read again) or ``done``. Money is integer micro-USD. ``captured_micro`` is what the card was charged, written only once the payment provider confirmed it. ``fax`` is the fax job once the order was released, with the carrier's evidence once it has any. |
| `signed_in` | boolean | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/one-time-sends/ONE_TIME_ORDER_ID/confirm \ -X POST \ -H "Content-Type: application/json" \ -d '{"token":"example"}'`
```

### GET `/v1/one-time-sends/{one_time_order_id}/receipt.pdf`

The receipt of a one-time order's fax as a one-page PDF

The delivery receipt of the order's fax: the state, the pages, the document hash, the carrier's evidence as it was reported, and what became of the card. It says charged only once the payment provider confirmed the capture. A key or session of the order's organization may read it, and so may the status token, as the header or as ?t=. 409 conflict while the fax has not ended or the order has no fax.

Credential: an API key, a signed-in session or the status token of the order. Scope: `fax:read`.

#### Parameters

GET /v1/one-time-sends/{one_time_order_id}/receipt.pdf parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `one_time_order_id` | path | string | yes |  |
| `t` | query | string or null | no | The status token, when no header carries it. |
| `X-FFA-Order-Token` | header | string | no | The status token of the order, for a caller without a key or a session. |

#### Responses

GET /v1/one-time-sends/{one_time_order_id}/receipt.pdf responses

| Status | Meaning |
| --- | --- |
| `200` | The receipt as a PDF |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `404` | not_found: no such resource for this credential. A resource of another organization answers the same. |
| `409` | The resource is in a state that refuses the call, or the Idempotency-Key was used with a different request (idempotency_key_conflict). error.code names the state. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |

#### Example

```
`curl https://api.faxforagents.com/v1/one-time-sends/ONE_TIME_ORDER_ID/receipt.pdf \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/one-time-sends/{one_time_order_id}/resend-confirmation`

Mail the confirmation link of a one-time order again

At most three times per order and once in ten minutes. The earlier links keep working.

Credential: an API key, a signed-in session or the status token of the order. Scope: `fax:send`.

#### Parameters

POST /v1/one-time-sends/{one_time_order_id}/resend-confirmation parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `one_time_order_id` | path | string | yes |  |
| `t` | query | string or null | no | The status token, when no header carries it. |
| `Idempotency-Key` | header | string | no | Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay. |
| `X-FFA-Order-Token` | header | string | no | The status token of the order, for a caller without a key or a session. |

#### Responses

POST /v1/one-time-sends/{one_time_order_id}/resend-confirmation responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `404` | not_found: no such resource for this credential. A resource of another organization answers the same. |
| `409` | The resource is in a state that refuses the call, or the Idempotency-Key was used with a different request (idempotency_key_conflict). error.code names the state. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |
| `503` | Something this call depends on is not available or not set up here, for example billing_unavailable or provider_unavailable. error.retryable says whether to send the same call again. |

#### Response fields

POST /v1/one-time-sends/{one_time_order_id}/resend-confirmation response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micro` | integer | yes |  |
| `aup_accepted` | boolean | no | Whether a person accepted the acceptable use policy and the terms for this order. False for an order a key created until the payer accepts on the order's page; the checkout needs it. |
| `aup_version` | string | yes |  |
| `authorized_at` | string or null | yes |  |
| `capture_deadline_at` | string or null | yes |  |
| `captured_micro` | integer | yes |  |
| `card` | object OneTimeCard or null | yes |  |
| `checkout_expires_at` | string or null | yes |  |
| `checkout_url` | string or null | yes |  |
| `confirm_deadline_at` | string or null | yes |  |
| `confirm_mail_sent_at` | string or null | yes |  |
| `cover` | object or null | yes |  |
| `created_at` | string | yes |  |
| `delete_after_send` | boolean | no | The sender asked for the document and the transmitted copy to be deleted the moment the fax ends in delivered, partial or failed. |
| `document_deleted` | boolean | no | True once no copy of the document is held: it was deleted after the send, by the retention period or by its owner, or the order ended before it was released and the uploaded file was removed. The order, the fax and the carrier evidence stay; they hold no document content. |
| `document_expires_at` | string or null | no | When the retention period deletes the stored document. Null before the release and once the document is deleted. |
| `document_id` | string or null | yes |  |
| `document_pages` | integer | yes |  |
| `document_sha256` | string | yes |  |
| `email` | string | yes |  |
| `email_verified` | boolean | yes |  |
| `environment` | string (live, test) | yes |  |
| `failure_code` | string or null | yes |  |
| `fax` | object or null | no | The fax job (the FaxJob shape) once the order was released; null before. |
| `fax_job_id` | string or null | yes |  |
| `id` | string | yes |  |
| `next` | string (checkout, confirm, wait, done) | yes |  |
| `price` | object OneTimePrice | yes |  |
| `queue` | object OneTimeQueue or null | no | The wait for a carrier line while the order has not ended and its fax is not on a line yet. Null for an ended order, a fax that is sending, and a test order. |
| `quote_id` | string or null | yes |  |
| `refunded_micro` | integer | no | What was refunded to the card after the charge, in micro-units, as the ledger holds it. Zero when nothing was refunded. captured_micro stays what was charged. |
| `released_at` | string or null | yes |  |
| `resend_allowed_at` | string or null | no | When the confirmation mail may be asked for again; null when it may not. |
| `route` | string | yes |  |
| `sender_name` | string | yes |  |
| `settled_at` | string or null | yes |  |
| `source` | string (web, api, mcp) | yes |  |
| `status` | string (draft, checkout_open, authorized, awaiting_confirmation, released, capturing, canceling, captured, released_hold, expired, refused, settle_failed) | yes |  |
| `status_url` | string or null | no | The order's page for the person who pays or confirms, with a fresh status token. Present on a read by a key or session of the order's organization while the order is not done. |
| `to` | string | yes |  |
| `updated_at` | string | yes |  |
| `warnings` | array of object | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/one-time-sends/ONE_TIME_ORDER_ID/resend-confirmation \ -X POST \ -H "Authorization: Bearer ffa_test_..."`
```