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
pip install faxforagents # the client
pip install "faxforagents[cli]" # plus the faxforagents command 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) 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.
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
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?
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.