Developers
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.
Create an account and an API key at upinvoice.eu/api/tokens.
Send the file as a base64 data URI to POST /api/process-document with its document_type.
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
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.
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
| 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.
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
}
}
| 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.
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.
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 →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
Everything an AI assistant needs to build an integration or to read invoices for you.
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 →Connect Claude, Cursor or any MCP client to UpInvoice and let it extract invoices and orders as a tool.
Open →Machine-readable reference: import it into Postman, generate a client or give it to your AI assistant.
Open →Summary of UpInvoice for language models: product, document types, prices and links.
Open →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 →