IDP Developer API: Document Data Extraction via REST, Webhooks & JSON

Data Alchemy exposes its Intelligent Document Processing (IDP) engine through a REST API and webhooks. With this data extraction API you send invoices, delivery notes (DDT), orders or contracts and get back structured, validated JSON — 99.8% accuracy with Claude and around 12 seconds for a one-page document (average time with Claude Sonnet), ready to post into an ERP such as SAP, Zucchetti or TeamSystem. This page is the developer API documentation for engineers and system integrators: REST endpoints, webhooks, the output data schema and Zucchetti API.

The REST API and webhooks are included in every licence: Basic, Business and Enterprise. On Basic they are how you integrate with your ERP; the AI agent is available from Business.

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.

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"

Quickstart: from the first call to JSON in 5 minutes

1. Generate the API key. From the Data Alchemy console create a key for the test or production environment. Keep the key server-side (environment variable or secret manager), never in client code or in the browser.
2. Send the first document. A multipart POST to /v1/documents with the PDF and the document_type starts the extraction and immediately returns an id and the processing status.
3. Register a webhook. A POST to /v1/webhooks declares the URL that will receive the document.processed event: no polling, and you get the data the moment processing finishes.
4. Verify the HMAC signature. Recompute the HMAC SHA-256 over the raw body and compare it with the X-Data-Alchemy-Signature header before reading the payload.
5. Map the JSON onto your ERP. The output schema is identical for every document type: write the mapping once and reuse it for invoices, delivery notes, orders, contracts and price lists.

A single integration covers the whole accounts-payable cycle: document intake, automatic classification, extraction, validation against your management system's master data and writing into SAP, Zucchetti or TeamSystem.

Webhooks: what they are and how they work

A webhook is an HTTP request that a service sends automatically to a URL you provide, the moment an event happens. It is the reverse of a normal API call: instead of you asking «is the document ready?», the service tells you as soon as it is. That is why a webhook is often described as a «reverse API» or an HTTP callback — the receiving application exposes a public endpoint and listens, while the service acts as the client.

In Data Alchemy it works like this: register a URL and you receive a POST to your endpoint as soon as a 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.

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 */ }
}

Webhooks vs polling: what's the difference?

With polling, your system repeatedly asks the API («is it ready yet?»), wasting calls until processing completes and adding a delay equal to your polling interval. With a webhook the notification fires the instant the document is ready: no empty calls, no artificial delay and far less load on both sides. Polling still makes a useful safety net — for example to catch up on a document if your endpoint was unreachable for a long stretch.

How to verify a webhook signature

Because your endpoint is public, anyone could POST to it. That is why every Data Alchemy webhook carries an X-Data-Alchemy-Signature header holding the HMAC SHA-256 of the raw request body, computed with your secret. Recompute the signature over the body you received and compare it with the header using a constant-time comparison: if they differ, drop the request. Always verify the signature before reading the payload.

import crypto from "node:crypto";

// Il body va letto grezzo: un JSON già parsato e riserializzato
// produrrebbe una firma diversa. / Read the raw body: a parsed and
// re-serialised JSON would produce a different signature.
function isFromDataAlchemy(rawBody, header, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  const received = header.replace("sha256=", "");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(received)
  );
}

OCR and data extraction API: how it differs from a classic OCR

If you're shopping for an OCR API to read invoices and documents, this API does that job and then goes one step further. An OCR returns the text it recognised on the image: a string, which someone then has to interpret to work out which number is the taxable amount and which is the VAT number. Here the call is the same — a multipart POST with your PDF — but the response is already typed JSON, with header, line items, totals and the outcome of validation against your ERP master data.

In practice: where an OCR leaves you writing the parser and maintaining it for every new supplier, here the parsing is the service. The document goes through text recognition, document-type classification, field extraction with a dedicated LLM and validation — and what reaches your code is the structure described in the output schema above, identical across document types.

Still deciding which of the two technologies you need? The invoice OCR software vs IDP AI comparison goes into detail. If you'd rather see it on a document of your own, try the extraction free with the Demo.

Rate limits, retries and error handling

Responses use standard HTTP status codes: 202 for a document accepted and processing, 200 when you retrieve the result, 401 for a missing or invalid API key, 422 for an unreadable document and 429 when you exceed the rate limit. Every error returns JSON with error.code and error.message.

On a 429 or any 5xx error, retry with exponential backoff so you don't pile pressure on a service that is already under load. Undelivered webhooks are retried automatically with increasing backoff, so no document.processed event is lost even if your endpoint stays unreachable for a few minutes.

HTTP/1.1 429 Too Many Requests
Retry-After: 30

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 30s."
  }
}

Explore the platform behind the API