For developers

Developer API: REST, Webhooks & Data Schema

Data Alchemy exposes its Intelligent Document Processing engine through a REST API, webhooks and SQL connectors. Send invoices, delivery notes (DDT), orders or contracts and get back structured, validated JSON — 99.8% accuracy in about 3 seconds per document, ready to post into your ERP. This page is the developer API documentation for engineers and system integrators.

Request API access See ERP integration →

What it is

An IDP API that turns documents into structured data

The developer API is the programmatic side of Data Alchemy's Intelligent Document Processing platform. Instead of clicking through a web app, your systems submit documents over HTTP and receive validated, structured data in return — so you can embed invoice, DDT and order extraction directly into your own software, automate your accounts-payable pipeline, or feed any ERP or CRM with no manual re-keying.

Authentication

Base URL and authentication

All requests use HTTPS against https://api.data-alchemy.ai/v1 and authenticate with a Bearer API key passed in the Authorization header. Keys are generated from the console and must be kept server-side, never exposed in the browser. Every response is UTF-8 JSON.

Request — submit document (cURL)

curl -X POST https://api.data-alchemy.ai/v1/documents \
  -H "Authorization: Bearer $DATA_ALCHEMY_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@fattura.pdf" \
  -F "document_type=invoice"

API reference

REST API reference: submit a document and read the data

The typical flow is asynchronous: you submit a document with a POST, receive an id and a processing status, then retrieve the result with a GET — or, better, let a webhook notify you when it completes. All endpoints are versioned under /v1.

POST/v1/documentsSubmit a document (PDF, XML, image) and start extraction. Returns an id and a status.

GET/v1/documents/{id}Retrieve the status and the extracted, validated data of a submitted document.

GET/v1/documentsList processed documents with filters by status, type and date range.

POST/v1/webhooksRegister an endpoint that will receive document.processed events in real time.

202 response — document processing

{
  "id": "doc_8a7f2c91",
  "status": "processing",
  "document_type": "invoice",
  "created_at": "2026-06-04T09:12:33Z",
  "webhook_url": "https://yourapp.example.com/hooks/data-alchemy"
}

Retrieve the result (cURL)

curl https://api.data-alchemy.ai/v1/documents/doc_8a7f2c91 \
  -H "Authorization: Bearer $DATA_ALCHEMY_API_KEY"

Webhooks

Webhooks: receive data the moment a document is ready

Register a URL and Data Alchemy sends a POST to your endpoint when each document has been processed, so you never poll. The payload contains the event, the document id, the confidence score and the extracted data following the output schema. Every request is signed with HMAC SHA-256 in the X-Data-Alchemy-Signature header so you can verify authenticity.

Webhook payload — document.processed

POST /hooks/data-alchemy  (X-Data-Alchemy-Signature: sha256=...)

{
  "event": "document.processed",
  "id": "doc_8a7f2c91",
  "status": "completed",
  "confidence": 0.998,
  "data": { /* schema di output — vedi sotto / see below */ }
}

Data schema

Output data schema (JSON)

Every document returns typed, validated JSON: header (supplier, number, dates), line items, totals, taxes and the result of validation against your ERP master data. The structure is consistent across document types, so you write the mapping to your ERP only once.

Output schema — invoice

{
  "document_type": "invoice",
  "header": {
    "supplier": {
      "name": "Rossi Forniture S.r.l.",
      "vat_number": "IT01234567890"
    },
    "invoice_number": "2026/00417",
    "issue_date": "2026-05-28",
    "currency": "EUR"
  },
  "line_items": [
    {
      "sku": "ART-0042",
      "description": "Cartone 30x20x15",
      "quantity": 12,
      "unit_price": 8.50,
      "total": 102.00,
      "vat_rate": 22
    }
  ],
  "totals": { "net": 102.00, "vat": 22.44, "gross": 124.44 },
  "validation": { "status": "validated", "erp_match": true }
}

document_type: Document type classified by the AI: invoice, delivery_note, order, contract, price_list.
header: Header data: supplier/customer details, VAT number, document number, dates and currency.
line_items: Array of lines: item code (SKU), description, quantity, unit price, total and VAT rate.
totals: Recomputed and re-checked totals: net amount (net), tax (vat) and document total (gross).
validation: Result of real-time validation against ERP master data, with an erp_match flag and any anomalies.

Integration methods

Four ways to integrate document extraction

REST API

Submit a document and retrieve its extracted, validated data as structured JSON, ready to map onto your ERP.

Webhooks

Event-driven async pipelines: Data Alchemy notifies your endpoint when processing completes, with no polling.

SQL connectors

Prefer database-level integration? Push extracted data straight into your system through direct SQL.

Email acquisition

Connect a Google Workspace or Microsoft 365 mailbox and let the AI ingest documents — zero-code integration.

Go deeper

Explore the platform behind the API

ERP integration

SAP, Zucchetti, TeamSystem

How extracted data is written into your management system via REST API, webhooks and SQL.

Learn more →Document extraction API

Document extraction API overview

The product-level view of the IDP API: capabilities, integration flow and use cases.

Learn more →IDP platform

Full IDP solution

Invoices, orders, contracts and price lists processed by the same AI platform.

Learn more →

FAQ

Frequently asked questions about the developer API

What is the Data Alchemy developer API?

It is the programmatic interface to Data Alchemy's Intelligent Document Processing (IDP) engine. Instead of using the web app, your systems submit documents — invoices, delivery notes (DDT), purchase orders, contracts, price lists — and receive back structured, validated data ready to write into your ERP or CRM.

Which integration methods are available?

Data Alchemy exposes a REST API and webhooks for event-driven workflows, plus direct SQL connectors for systems that prefer database-level integration. Documents can also be acquired automatically from a Google Workspace or Microsoft 365 mailbox, with no code at all.

What format does the extracted data come back in?

Extracted fields are returned as structured JSON — header data, line items, totals, taxes and document references — already validated against your ERP master data, so it can be mapped directly onto your system of record.

How do authentication and webhook security work?

Requests authenticate with a Bearer API key in the Authorization header over HTTPS. Outgoing webhooks are signed with HMAC SHA-256 in the X-Data-Alchemy-Signature header, so you can verify each notification genuinely comes from Data Alchemy before processing it.

How accurate and fast is the extraction?

Data Alchemy assigns a dedicated LLM to each document model (today Claude AI), reaching 99.8% accuracy in about 3 seconds per document, with no templates and no per-layout training.

Which ERPs can I write the data into?

The API is system-agnostic: native integrations exist for SAP, Zucchetti and TeamSystem, and the REST API, webhooks and SQL connectors let you push structured data into any other ERP, CRM or internal application.

Build with the developer API

Tell us about your use case and we'll set up API access and walk you through integration on your real documents — no commitment.

Request API access