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

Data Alchemy exposes its Intelligent Document Processing (IDP) engine through a REST API, webhooks and SQL connectors. With this data extraction API you 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 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 integration via API.

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"

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)
  );
}

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