Python SDK

Updated

The Python package is named faxforagents and has been on PyPI since 2026-10-30. Install it with pip install faxforagents. Python 3.10 or later, two dependencies, httpx and pydantic. The REST calls further down work with httpx or requests as well, so nothing here depends on the package.

Status

Published. The package is built from the same OpenAPI document as this site and released through PyPI trusted publishing. The quickstart below is the one from the package's README. The source is at github.com/faxforagents/sdk-python and the package page is pypi.org/project/faxforagents.

Install and send with the package

Shell
pip install faxforagents            # the client
pip install "faxforagents[cli]"     # plus the faxforagents command
Python
import os
from faxforagents import Client

os.environ["FAXFORAGENTS_API_KEY"] = "ffa_test_..."      # or export it in the shell

with Client() as ffa:
    doc = ffa.documents.create(text="Hello from an agent.", filename="hello")
    print(doc.id, doc.page_count, doc.sha256[:12])

    quote = ffa.quotes.create(document_id=doc.id, to="+15550000001")
    print(quote.amount_micro, "micro, expires", quote.expires_at)

    fax = ffa.faxes.create(quote_id=quote.id)              # Idempotency-Key minted for you
    print(fax.id, fax.state)                               # queued, never delivered yet

    fax = ffa.faxes.wait(fax.id)                           # polls until a terminal state
    print(fax.state, fax.pages_sent, fax.evidence)         # delivered, 1, {...}

    for job in ffa.faxes.iter(state="failed"):             # follows next_cursor
        print(job.id, job.failure_code)

A test key is tied to test mode, where the destination number picks the outcome. The same calls exist in async form, with AsyncClient and await on every call.

Send a fax with httpx

Each HTTP example runs independently. Export FAXFORAGENTS_API_KEY in your shell. The upload example reads contract.pdf from the current directory.

The send makes a new Idempotency-Key with uuid.uuid4(), so the example runs every time. In your own code, derive the key from your record, such as the order id. A retry then returns the same job.

Python
import os
import uuid
import httpx

API = "https://api.faxforagents.com/v1"
KEY = os.environ["FAXFORAGENTS_API_KEY"]
h = {"Authorization": f"Bearer {KEY}"}

with httpx.Client(base_url=API, headers=h, timeout=30) as c:
    doc = c.post("/documents", json={"markdown": "# PO 4411\n\nPlease confirm."}).raise_for_status().json()
    quote = c.post("/fax-quotes", json={"document_id": doc["id"], "to": "+15550000001"}).raise_for_status().json()
    job = c.post("/faxes", json={"quote_id": quote["id"]}, headers={"Idempotency-Key": str(uuid.uuid4())}).raise_for_status().json()
    print(job["id"], job["state"])  # fax_..., queued

Upload a PDF

Python
from pathlib import Path
import os
import httpx

API = "https://api.faxforagents.com/v1"
KEY = os.environ["FAXFORAGENTS_API_KEY"]
h = {"Authorization": f"Bearer {KEY}"}

path = Path("contract.pdf")  # an existing PDF in the current directory

with httpx.Client(base_url=API, headers=h, timeout=30) as c:
    size = path.stat().st_size
    up = c.post("/uploads", json={"filename": path.name, "size_bytes": size}).raise_for_status().json()
    httpx.put(up["upload_url"], content=path.read_bytes(), timeout=120).raise_for_status()
    c.post(f"/uploads/{up['id']}/complete", json={}).raise_for_status()
    doc = c.post("/documents", json={"upload_id": up["id"]}).raise_for_status().json()

How do I page through jobs?

Python
import os
import httpx

API = "https://api.faxforagents.com/v1"
KEY = os.environ["FAXFORAGENTS_API_KEY"]
h = {"Authorization": f"Bearer {KEY}"}

with httpx.Client(base_url=API, headers=h, timeout=30) as c:
    cursor = None
    while True:
        page = c.get("/faxes", params={"limit": 50, "cursor": cursor}).raise_for_status().json()
        for job in page["items"]:
            print(job["id"], job["state"])
        cursor = page.get("next_cursor")
        if not cursor:
            break

How do I verify a webhook?

The reference verifier is on the webhooks page. The package ships the same function as faxforagents.webhooks.verify_webhook.

Errors

Every non-2xx body is the error envelope. Read error.code and error.retryable. Retry a retryable call with the same Idempotency-Key. The errors page lists every code.

Start in test mode. It is free.

A test API key works in test mode only. Every outcome can be rehearsed there before a wallet is funded.

Get an API key Read the quickstart