Factum Parse API

⚡️ Quickstart — Time-to-first-call < 60s

Send a textual payload (invoice, F24, free text) and get back a structured DocumentEnvelope v2. Authentication: X-API-Key header.

Fastest First Call Raw Text / JSON — test the endpoint in 30 seconds with a text payload. For production PDF/XML/multipart workflows, see Endpoint Reference.

cURL

curl -X POST https://api.factum.pyragogy.org/v1/parse \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Invoice no. 2026/001 dated 15/03/2026. Supplier: ACME S.r.l. — Via Roma 1, Milan. VAT IT01234567890. Client: Mario Rossi. Total: € 1,220.00. Taxable: € 1,000.00. VAT 22%: € 220.00.",
    "doc_type": "auto"
  }'

Python (httpx)

import httpx

payload = {
    "text": "Invoice no. 2026/001. Supplier: ACME S.r.l. Total: € 1,220.00.",
    "doc_type": "auto",
}

resp = httpx.post(
    "https://api.factum.pyragogy.org/v1/parse",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json=payload,
)
resp.raise_for_status()
print(resp.json())

TypeScript (fetch)

// Replace with your actual API key
const API_KEY = "YOUR_API_KEY";

const response = await fetch("https://api.factum.pyragogy.org/v1/parse", {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Invoice no. 2026/001. Supplier: ACME S.r.l. Total: € 1,220.00.",
    doc_type: "auto",
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

Go

package main

import (
    "bytes"
    "fmt"
    "net/http"
)

func main() {
    body := []byte(`{"text":"Invoice no. 2026/001. Supplier: ACME S.r.l. Total: € 1,220.00.","doc_type":"auto"}`)
    req, _ := http.NewRequest("POST", "https://api.factum.pyragogy.org/v1/parse", bytes.NewReader(body))
    req.Header.Set("X-API-Key", "YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    fmt.Println(res.Status)
}

PHP

<?php
$apiKey = 'YOUR_API_KEY'; // Sostituisci con la tua chiave
$ch = curl_init('https://api.factum.pyragogy.org/v1/parse');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'text' => 'Invoice no. 2026/001. Supplier: ACME S.r.l. Total: € 1,220.00.',
        'doc_type' => 'auto',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
if ($response === false) throw new RuntimeException(curl_error($ch));
curl_close($ch);
echo $response;

---

🧪 Try it in your browser

Enter your X-API-Key and a document excerpt to test the endpoint directly from your browser. The response is displayed with syntax highlighting.

🔑 X-API-Key

🎯 Quick Presets

Preset 1: FatturaPA XML (Fast-path deterministic, 100% RAM)Preset 2: Free-text / Receipt (LLM Fallback with PII Sanitization)Preset 3: Invalid Document (RFC 7807 Error Demo — 422 Unprocessable)

📄 Document Text

📋 Document Type

autofatturaf24generico

Show PII pseudonymization payload

Zero Disk I/O

🛡️ Pseudonymized Payload (sent to LLM)

▶️ Run Parse (Demo)

📋 Copy JSON

📦 Response JSON

⚠️ Demonstrational execution with rate-limiting. Your key is never stored nor sent to third parties.

Response — ParseResponse with DocumentEnvelope v2

{
  "job_id": "3f2b5e6a-0000-4000-8000-000000000004",
  "status": "done",
  "document_type": "invoice",
  "provider_used": "fast-path",
  "prompt_version": "fast-path-v1",
  "confidence": 1.0,
  "cost_usd": 0.0,
  "tokens": 0,
  "fallbacks": [],
  "content_hash": "a1b2c3d4e5f67890abcdef1234567890abcdef12",
  "result": {
    "schema_version": "2.0",
    "document_type": "invoice",
    "meta": {
      "confidence": 1.0,
      "provider": "fast-path",
      "prompt_version": "fast-path-v1"
    },
    "payload": {
      "kind": "invoice",
      "cedente_prestatore": {
        "Denominazione": "ACME S.r.l.",
        "Indirizzo": "Via Roma 1, Milano",
        "PartitaIVA": "IT01234567890"
      },
      "cessionario_committente": {
        "Denominazione": "Mario Rossi"
      },
      "corpi": []
    }
  },
  "error": null
}

Key points

Aspect	Detail
Auth	X-API-Key header on business endpoints; fail-closed
Document type	auto detects; explicit fattura, f24, generico available
ZDR Privacy	Direct text is stateless; PII mapping is request-scoped RAM
Deterministic	FatturaPA XML → 100% deterministic, 0 tokens, 0 cost
LLM fallback	PDF/invoice images → PII pseudonymization → LLM extraction

What’s next?

• API Reference — Endpoints for full HTTP contract details
• Privacy Model for zero-retention semantics and the ZDR boundary
• Rizzo PII Sidecar for the pseudonymization pipeline

---

💰 Pricing

Factum Parse is self-service via Lemon Squeezy. Pay monthly, get the API Key instantly via webhook.

Tier	Price / month	Rate limit	Best for
Starter	€29	60 req/min	Testing, low volume
Pro	€99	300 req/min	Production, mid volume
Custom	Contact us	1000+ req/min	Enterprise, high volume

Payment by card/crypto (Lemon Squeezy). Key activates automatically on order confirmation.

➡️ Buy now — €29/month

Also available on Zyla API Hub for discovery and enterprise invoicing.

---

💬 Support & Contacts

For technical support, enterprise contracts and commercial inquiries:

• Email: info@pyragogy.org
• GitHub Issues: factum-community — bug reports, parser requests, discussions
• Documentation: docs.factum.pyragogy.org