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

# Agent fax lines

> Provision a fax line for an agent, receive fax briefs, and send PDF faxes safely

# Agent fax lines

<Warning>
  Agent fax lines are in limited rollout. Interchange provisions each line with
  the customer and enables the account before the fax API becomes available.
  There is not yet a self-service number picker.
</Warning>

An agent fax line gives a storefront agent a real telephone number for inbound
and outbound PDF fax delivery. It is useful for partners whose existing
workflows still produce paper or fax documents.

## How inbound fax works

When the assigned number receives a fax, Interchange:

1. verifies the carrier-signed event and copies the PDF into private storage;
2. verifies the stored file and extracts bounded document text;
3. treats that text as untrusted external input to the assigned storefront
   agent; and
4. renders the agent's response as a PDF and sends it back to the verified
   originating fax number.

Interchange does not store the carrier's temporary media URL or expose it to
the agent. Fax files are isolated by customer and expire under the fax storage
retention policy. Delivery metadata and content digests remain available for
idempotency and audit without retaining telephone numbers in the command
ledger.

## Provision a line

Contact Interchange to request a line during the limited rollout. Choose the
customer account, storefront agent, country or region, and preferred area
code. Interchange assigns the carrier number, verifies that it belongs to the
fax application, and activates its route to the selected agent.

Provisioning is currently an operator action. API keys cannot create or move a
line, and entering an arbitrary existing number does not claim it. Bring-your-
own-number porting and a self-service distribution card are planned separately.

## Send a fax

Send an outbound PDF with `POST /api/v2/communications/faxes`. The caller needs
`interchange:write`, access to the endpoint's customer, and enrollment in the
limited rollout.

```bash theme={null}
curl -X POST "https://api.interchange.io/api/v2/communications/faxes" \
  -H "Authorization: Bearer $INTERCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "df3b1f38-77ad-4e2e-ad67-594433cf1be7",
    "endpointId": "123",
    "to": "+12025550101",
    "mediaUrl": "https://relay.example.com/fax.pdf",
    "mediaSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }'
```

| Field         | Required | Description                                                                                      |
| ------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `requestId`   | Yes      | A UUID owned by the caller. Reuse it only to retry the same intended fax.                        |
| `endpointId`  | Yes      | The Interchange fax-line ID, represented as a numeric string.                                    |
| `to`          | Yes      | Destination telephone number in E.164 format.                                                    |
| `mediaUrl`    | Yes      | Temporary HTTPS URL from which the carrier can fetch the PDF. Embedded credentials are rejected. |
| `mediaSha256` | Yes      | Lowercase SHA-256 digest of the PDF at `mediaUrl`.                                               |

The URL must remain reachable long enough for carrier ingestion. Use a short
expiry and do not require cookies, interactive login, or request headers that
the carrier cannot provide.

An accepted request returns HTTP `202`:

```json theme={null}
{
  "data": {
    "fax": {
      "providerFaxId": "b4c7f7e8-33c4-4af6-82f4-55a41ba93427",
      "providerStatus": "queued",
      "duplicate": false
    }
  },
  "error": null
}
```

`queued` confirms carrier acceptance, not final delivery to the remote fax
machine. `duplicate` is `true` when Interchange returns the result of an earlier
completed request with the same `requestId`.

## Retry and error behavior

Interchange binds `requestId` to the endpoint, destination, and PDF digest.
Repeating that exact command is safe. Reusing the UUID with different input
returns `409`.

| Status                          | Meaning                                                                                             | Action                                                                        |
| ------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `400`                           | A field is invalid, the number is not E.164, or the media URL is not HTTPS.                         | Correct the request.                                                          |
| `401` or `403`                  | The credential is missing, invalid, or lacks `interchange:write`.                                   | Correct the credential or permission.                                         |
| `404`                           | The rollout is disabled or the fax line is not active for this customer.                            | Ask Interchange to verify enrollment and provisioning.                        |
| `409`                           | The request UUID was reused with different immutable input, or an earlier submission is unresolved. | Keep the original input or use a new UUID only for a genuinely new fax.       |
| `503` with `submission_unknown` | The carrier may have accepted the request, but Interchange did not receive a definitive result.     | Do not submit the same fax under a new UUID; ask Interchange to reconcile it. |

Interchange never automatically repeats an ambiguous carrier submission. This
prevents a network timeout from producing two physical faxes.