Developers

Invoice and order data extraction API

Send a PDF, a scan or a phone photo and get JSON with the supplier or customer, references, dates, totals, VAT and product lines, already checked against the document totals. Three document types: supplier invoices, purchase orders and customer orders.

At a glance

  • Synchronous REST API with JSON in and out
  • PDF, JPEG and PNG; any layout or language, no templates
  • 1 credit per processed document; errors and retries are free
  • Idempotency-Key header for safe retries

Quick start

  1. 1

    Create an account and an API key at upinvoice.eu/api/tokens.

  2. 2

    Send the file as a base64 data URI to POST /api/process-document with its document_type.

  3. 3

    Read the JSON, check the warnings and create the document in your system.

curl -sS https://upinvoice.eu/api/process-document \
  -H "Authorization: Bearer $UPINVOICE_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --max-time 120 \
  -d @- <<EOF
{
  "document_type": "supplier_invoice",
  "invoice_file": "data:application/pdf;base64,$(base64 -w0 invoice.pdf)",
  "company_name": "Demo Company SL",
  "company_tax_id": "B12345678"
}
EOF

Endpoints

  • POST/api/process-document

    Extract one document. Use this one.

  • GET/api/check

    Free. Validates the key and returns plan, remaining credits and supported document types.

  • POST/api/process-invoice

    Legacy, supplier invoices only. Kept for older Dolibarr modules.

Authentication

Send your API key as a bearer token and always add Accept: application/json, or an invalid key is answered with a redirect instead of a 401.

Authorization: Bearer <your-api-key>
Accept: application/json

Request

Field Description
document_type Required. supplier_invoice (invoice or credit note received), supplier_order (your purchase order or a supplier's order confirmation) or customer_order (an order a customer sent you).
invoice_file Required, same name for every type. Data URI data:<mime>;base64,<content>. Accepted: application/pdf, image/jpeg, image/png, up to 5 MB per file.
company_name, company_tax_id Recommended. Your own company's name and tax ID, so the AI never mistakes you for the supplier or customer.

Processing is synchronous: usually 3 to 6 seconds, up to 30 seconds for long multi-page PDFs. Use a client timeout of at least 90 seconds and up to 5 requests in parallel.

Response

The data object depends on the document type. Supplier invoices return supplier, ref_supplier, date, totals, VAT and lines (credit notes with negative amounts). Orders return thirdparty, ref_document, order and delivery dates, currency, notes, lines and warnings. Every field is described in the OpenAPI spec.

{
  "success": true,
  "data": {
    "supplier": {
      "name": "Example Supplies SL",
      "idprof1": "B00000000",
      "tva_intra": "ESB00000000",
      "address": "Calle Mayor 1",
      "zip": "46001",
      "town": "Valencia",
      "country_code": "ES",
      ...
    },
    "ref_supplier": "F-2026-0457",
    "date": "2026-11-12",
    "total_ht": 230,
    "total_tva": 48.3,
    "total_ttc": 278.3,
    "tva_tx": 21,
    "lines": [
      {
        "product_desc": "Printer toner, black",
        "product_ref": "TN-2420",
        "qty": 4,
        "subprice": 50,
        "remise_percent": 10,
        "tva_tx": 21,
        "total_ht": 180,
        "total_tva": 37.8,
        "total_ttc": 217.8,
        "product_type": 0,
        "accounting_code": "602"
      },
      ...
    ],
    "available_points": 72
  }
}

Good to know

  • Missing text fields are empty strings; dates are YYYY-MM-DD or empty.
  • Line totals already include discounts; use them as the reference amounts.
  • If an order has warnings (document_type_mismatch, thirdparty_matches_own_company), ask a person before creating it.
  • Orders without prices come with zero amounts: take the prices from your catalogue.

Errors

Status Meaning
401 Missing or invalid API key.
409 A request with the same Idempotency-Key is still running. Wait for Retry-After and retry with the same key.
422 Invalid field, or Idempotency-Key reused with another file. Fix the request.
400 Invalid data URI, unsupported file, no credits or unreadable document. Nothing is charged. Call /api/check to tell a credit problem from a file problem.

The error field is a human-readable message, not a stable code.

Safe retries with Idempotency-Key

Send a unique Idempotency-Key per document (a UUID or your own document ID). If the connection drops, repeat the same request with the same key: you get the stored result with the header Idempotent-Replayed: true and you are not charged twice. Keys are kept for 48 hours.

Pricing

The extraction runs on the UpInvoice AI and is billed in credits: one credit per processed document. Credits come with a monthly or yearly plan, or as extra packs when you need more. The first 10 documents are free, no credit card required.

See plans and prices →

Code examples

import base64, os, uuid
import requests  # pip install requests

with open("invoice.pdf", "rb") as fh:
    data_uri = "data:application/pdf;base64," + base64.b64encode(fh.read()).decode()

resp = requests.post(
    "https://upinvoice.eu/api/process-document",
    headers={
        "Authorization": "Bearer " + os.environ["UPINVOICE_API_KEY"],
        "Accept": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it if you retry
    },
    json={
        "document_type": "supplier_invoice",
        "invoice_file": data_uri,
        "company_name": "Demo Company SL",
        "company_tax_id": "B12345678",
    },
    timeout=120,
)
result = resp.json()
if resp.ok:
    invoice = result["data"]
    print(invoice["supplier"]["name"], invoice["ref_supplier"], invoice["total_ttc"])
else:
    print(resp.status_code, result.get("error") or result.get("message"))
$dataUri = 'data:application/pdf;base64,' . base64_encode(file_get_contents('invoice.pdf'));

$ch = curl_init('https://upinvoice.eu/api/process-document');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 120,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('UPINVOICE_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
        'Idempotency-Key: ' . bin2hex(random_bytes(16)), // reuse it if you retry
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'document_type' => 'supplier_invoice',
        'invoice_file' => $dataUri,
        'company_name' => 'Demo Company SL',
        'company_tax_id' => 'B12345678',
    ]),
]);
$result = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($status === 200) {
    $invoice = $result['data'];
    echo $invoice['supplier']['name'], ' ', $invoice['ref_supplier'], ' ', $invoice['total_ttc'], PHP_EOL;
} else {
    echo $status, ' ', $result['error'] ?? $result['message'] ?? '', PHP_EOL;
}
curl -sS https://upinvoice.eu/api/process-document \
  -H "Authorization: Bearer $UPINVOICE_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --max-time 120 \
  -d @- <<EOF
{
  "document_type": "supplier_invoice",
  "invoice_file": "data:application/pdf;base64,$(base64 -w0 invoice.pdf)",
  "company_name": "Demo Company SL",
  "company_tax_id": "B12345678"
}
EOF

For AI agents

Everything an AI assistant needs to build an integration or to read invoices for you.

Agent Skill

Instructions, field rules and a helper script so an AI agent (Claude Code and other agents compatible with SKILL.md) writes a correct integration on the first try.

Open →

MCP server

Connect Claude, Cursor or any MCP client to UpInvoice and let it extract invoices and orders as a tool.

Open →

OpenAPI 3.1

Machine-readable reference: import it into Postman, generate a client or give it to your AI assistant.

Open →

llms.txt

Summary of UpInvoice for language models: product, document types, prices and links.

Open →

Using Dolibarr?

You do not need to write code: the free UpInvoice module for Dolibarr already uses this API and creates the invoices and orders for you.

See the Dolibarr module →