DEV Community

Sonam
Sonam

Posted on

Build a Fax-to-JSON Pipeline in Python

#telnyx #ai #python #devrel

Fax is still part of a lot of real business workflows.

Healthcare, insurance, logistics, legal, finance, and back-office teams still receive forms, invoices, purchase orders, prescriptions, claims, and signed documents by fax. The problem is what happens after the fax arrives.

This Python example shows how to receive a Telnyx fax event and turn document text into structured JSON with Telnyx AI Inference:

https://github.com/team-telnyx/telnyx-code-examples/tree/main/fax-to-structured-data-pipeline-python

What We Are Building

The app is a small Flask API with these routes:

POST /webhooks/fax   # receive Telnyx fax events
POST /extract        # extract structured data from document text
GET  /faxes          # list queued fax metadata
GET  /extracted      # list recent extraction results
GET  /health         # health check
Enter fullscreen mode Exit fullscreen mode

The extraction route supports:

  • invoices
  • purchase orders
  • prescriptions
  • auto-detected document types

The AI call uses:

POST /v2/ai/chat/completions
Enter fullscreen mode Exit fullscreen mode

Run It Locally 

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/fax-to-structured-data-pipeline-python
cp .env.example .env
pip install -r requirements.txt
python app.py
Enter fullscreen mode Exit fullscreen mode

Set these values in .env:

TELNYX_API_KEY=your_telnyx_api_key
TELNYX_PUBLIC_KEY=your_telnyx_public_key
AI_MODEL=moonshotai/Kimi-K2.6
HOST=127.0.0.1
Enter fullscreen mode Exit fullscreen mode

Try the Extraction Endpoint

You do not need to send a live fax to test the extraction path. Send document text directly:

curl -X POST http://localhost:5000/extract \
  -H "Content-Type: application/json" \
  -d '{
    "type": "invoice",
    "text": "Invoice #INV-1042 from Acme Medical Supplies dated 2026-07-01. Due 2026-07-31. Bill to North Clinic. Item: Nitrile gloves, quantity 10, unit price 12.50, total 125.00. Item: Face masks, quantity 5, unit price 20.00, total 100.00. Subtotal 225.00. Tax 18.00. Total 243.00. Payment terms Net 30."
  }' | python3 -m json.tool
Enter fullscreen mode Exit fullscreen mode

The app asks the model for invoice-shaped JSON:

{
  "vendor": "Acme Medical Supplies",
  "invoice_number": "INV-1042",
  "date": "2026-07-01",
  "due_date": "2026-07-31",
  "line_items": [
    {
      "description": "Nitrile gloves",
      "quantity": 10,
      "unit_price": 12.5,
      "total": 125
    }
  ],
  "subtotal": 225,
  "tax": 18,
  "total": 243,
  "payment_terms": "Net 30"
}
Enter fullscreen mode Exit fullscreen mode

Try Auto Detection

Use type: "auto" when you want the model to infer the document type:

curl -X POST http://localhost:5000/extract \
  -H "Content-Type: application/json" \
  -d '{
    "type": "auto",
    "text": "Purchase Order PO-7781. Vendor: Harbor Office Supply. Ship to: 500 Market St, San Francisco, CA. SKU CHAIR-22, ergonomic chair, quantity 12, unit price 199.00. Total 2388.00. Delivery requested 2026-07-20."
  }' | python3 -m json.tool
Enter fullscreen mode Exit fullscreen mode

How the Fax Webhook Fits In

The live fax route is:

POST /webhooks/fax
Enter fullscreen mode Exit fullscreen mode

The app verifies the Telnyx webhook signature before trusting the event. When it receives fax.received, it queues metadata like:

  • fax ID
  • sender
  • recipient
  • page count
  • media URL
  • status
  • timestamp

For local webhook testing, expose your app:

ngrok http 5000
Enter fullscreen mode Exit fullscreen mode

Then set your Telnyx Fax Application webhook URL to:

https://<id>.ngrok.io/webhooks/fax
Enter fullscreen mode Exit fullscreen mode

Production Notes

The demo keeps state in memory. For production, I would add:

  • media download from the fax media_url
  • OCR before extraction
  • persistent storage
  • schema validation per document type
  • retry handling
  • human review for regulated data
  • audit logs and retention policies
  • queue workers for high-volume intake

The example repo is also agent-readable. A coding agent can inspect the README, API reference, guide, environment file, and app code, then help you add OCR, storage, tests, queue workers, or stricter validation.

Resources

Top comments (0)