Fax API

Receive faxes on a Telnyx-provisioned fax number and read past faxes. Sending a fax goes through the unified Messaging API at POST /api/v1/messages/fax. Base path: /api/v1/fax Authentication: API key (X-API-Key) or session JWT.

Method	Path	Purpose
`GET`	`/api/v1/fax/`	List faxes
`GET`	`/api/v1/fax/{id}`	Get a fax message row
`GET`	`/api/v1/fax/{id}/status`	Get current status only

Using the SDKs

Prefer the typed client, but this page’s endpoint has no helper yet — the generic request() keeps auth/retries and the { data, meta } envelope identical:

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const { data } = await orbit.request<unknown>(
  "POST",
  "/fax/send",
  {}
);

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("POST", "/fax/send", {})

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Raw curl in the body of this page works identically. Full SDK index at SDK quickstart.

Worked examples

1. Receive — list and read a fax

Faxes received on your fax number land in the message history with channel: "fax". List them newest-first:

curl "https://api.orbit.devotel.io/api/v1/fax/?limit=10" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "msg_6f1c2a9b4e8d4a2c8f0e1b3d5a7c9e2f",
      "channel": "fax",
      "from": "+14155550123",
      "to": "+13125550199",
      "status": "delivered",
      "external_id": "fax_2a1b3c4d5e",
      "created_at": "2026-08-23T14:12:07.000Z"
    }
  ],
  "meta": {
    "request_id": "req_ab12cd34",
    "timestamp": "2026-08-23T14:12:08.240Z",
    "pagination": { "cursor": null, "has_more": false, "total": 1 }
  }
}

Read one fax by its message ID:

curl https://api.orbit.devotel.io/api/v1/fax/msg_6f1c2a9b4e8d4a2c8f0e1b3d5a7c9e2f \
  -H "X-API-Key: dv_live_sk_your_key_here"

An ID that doesn’t belong to a fax in your account returns 404.

2. Poll delivery status

GET /api/v1/fax/{id}/status returns just the live delivery status. The result is cached for ~10s per tenant — poll no more often than that. Statuses move queued → sending → sent → delivered (or failed).

curl https://api.orbit.devotel.io/api/v1/fax/msg_6f1c2a9b4e8d4a2c8f0e1b3d5a7c9e2f/status \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "id": "msg_6f1c2a9b4e8d4a2c8f0e1b3d5a7c9e2f",
    "status": "delivered"
  },
  "meta": {
    "request_id": "req_ef56gh78",
    "timestamp": "2026-08-23T14:14:01.102Z"
  }
}

Calling it before the fax has been dispatched (no provider-side ID yet) returns 404 — send first, then poll.

3. Send — through the Messaging API

Sending goes through the unified Messaging API. PDF or TIFF, capped at 50 MB:

curl -X POST https://api.orbit.devotel.io/api/v1/messages/fax \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+13125550199",
    "from": "+14155550123",
    "media_url": "https://storage.example.com/docs/invoice-1042.pdf"
  }'

{
  "data": {
    "id": "msg_a1b2c3d4e5f60718293a4b5c6d7e8f90",
    "channel": "fax",
    "status": "queued",
    "from": "+14155550123",
    "to": "+13125550199",
    "external_id": null,
    "created_at": "2026-08-23T14:15:44.390Z"
  },
  "meta": {
    "request_id": "req_ij90kl12",
    "timestamp": "2026-08-23T14:15:44.618Z"
  }
}

Both to and from must be E.164, and from must be one of your fax-capable numbers. Take the id from the 202 response and poll GET /api/v1/fax/{id}/status (above) for the live result. See the Messaging API for the full send surface.

API Reference

All Endpoints

Fax API: send and receive faxes with status webhooks

Fax API

Using the SDKs

Worked examples

1. Receive — list and read a fax

2. Poll delivery status

3. Send — through the Messaging API

See also

​Fax API

​Using the SDKs

​Worked examples

​1. Receive — list and read a fax

​2. Poll delivery status

​3. Send — through the Messaging API

​See also

Fax API

Using the SDKs

Worked examples

1. Receive — list and read a fax

2. Poll delivery status

3. Send — through the Messaging API

See also