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

# Fax

> Send and receive faxes over the Orbit Fax API

# Fax

Orbit's Fax channel sends and receives T.38 / G.711 faxes via Telnyx Programmable Fax. Documents are delivered as PDF or TIFF; status updates flow through the same webhook contract as other channels.

Fax is on-success-charge: Orbit only bills your wallet when the carrier confirms a successful fax transmission. Failed attempts (busy, no-answer, line-quality) are NOT billed.

## Send a fax

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/messages/fax \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+18005551234",
    "media_url": "https://example.com/contract.pdf",
    "quality": "high",
    "status_callback": "https://example.com/webhooks/fax",
    "metadata": { "order_id": "ord_123" }
  }'
```

### Response

```json theme={null}
{
  "data": {
    "id": "msg_a1b2c3d4e5f6g7h8",
    "status": "queued",
    "channel": "fax"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-05-09T00:00:00Z"
  }
}
```

## Capabilities

* **Outbound fax** — PDF or TIFF input; carrier converts to T.38 packets in real time.
* **Inbound fax** — incoming faxes are stored as PDF in Orbit's secure storage, with the page count, sender ANI, and a download URL POSTed to your webhook.
* **Quality** — set `quality` to `normal`, `high`, or `very_high` to control the fax resolution.
* **Document size** — PDF or TIFF up to 50 MB per outbound fax (Telnyx's hard media-size limit); multi-page documents are supported, with no separate page-count cap.
* **Delivery status** — outbound fax outcomes arrive on the channel-agnostic `message.delivered` / `message.failed` webhook events with `channel: "fax"` (there is no separate `fax.*` event to subscribe to). Each payload carries `message_id`, `status`, `state_class`, and `is_terminal` for reconciliation.
* **Per-tenant carrier connection** — orgs can attach a dedicated Telnyx Fax application for compliance / data-residency.

## Status flow

`queued` → `sending` → `sent` → `delivered` (or `failed`)

## Common errors

A failed send returns the standard JSON error envelope whose `error.code` is one
of the values below.

| Code                     | HTTP | Cause                                                                                                       | Fix                                                                                     |
| ------------------------ | ---- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `INVALID_PHONE_NUMBER`   | 422  | `to` is not a valid E.164 phone number.                                                                     | Verify the format `+<country><area><number>`.                                           |
| `MISSING_REQUIRED_FIELD` | 422  | `from` or `media_url` was omitted — both are required for an outbound fax.                                  | Supply a valid `from` fax number and a `media_url` pointing at the PDF or TIFF to send. |
| `VALIDATION_ERROR`       | 422  | Another request field failed validation (for example a `status_callback_secret` with no `status_callback`). | Check the `details` in the response for the offending field.                            |

### Failed transmissions

A fax that is accepted but cannot be delivered (busy line, no answer, no fax
tone, poor line quality, or a recipient that rejects the handshake) is reported
asynchronously on the `message.failed` webhook with the record marked `failed`.
When the carrier supplies a diagnostic, Orbit passes it through unchanged in the
`error_code` and `error_message` fields — these carry the carrier's own code and
description, not a fixed Orbit enum, so the exact set of values depends on the
upstream carrier. When no carrier detail is available, the record simply reaches
`failed` with no further reason. Failed faxes are never billed.

## Pricing

Per-page on success only. International rates vary by destination. See the [pricing page](https://orbit.devotel.io/pricing).