Exports

Besides the JSON response, Constaia generates ready-to-use files with the extracted data and the verdict. Exports are included in the price of the analysis: they don't use credits.

FormatsCopy Anchor Link

In csv and xlsx, each row starts with some common columns (id, file, type, verdict, reasons, signals, date), continues with the extracted fields and ends with a metadata.<key> column for each metadata key. Nested fields (e.g. an invoice's lines) go as JSON in their cell. Column headers are in Spanish. The CSV uses ; as separator, decimal commas and UTF-8 with BOM, so Spanish-locale Excel opens it correctly straight away.

The field columns depend on the document type. The quickest way to see them is to generate an export in test mode, which is free.

Two ways to get themCopy Anchor Link

1. When analysing: options.exportCopy Anchor Link

Ask for the formats in the same request. When the analysis finishes, exports holds one signed URL per format:

curl https://api.constaia.com/v1/analyze \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F file=@invoice.pdf \
  -F 'options={"expect":"invoice","export":["xlsx","json"]}'

"exports": {
  "xlsx": "https://api.constaia.com/v1/files/exp_01J9Z…?expires=1790244002&sig=…",
  "json": "https://api.constaia.com/v1/files/exp_01J9Z…?expires=1790244002&sig=…"
}

• The URLs don't need an API key: the signature is the authorisation. Treat them as secrets and don't publish them.
• They expire after 24 hours. After that they return 404.
• GET /v1/analyses/{id} returns the links that are still valid in exports.
• If the analysis is async, the URLs arrive in the analysis.completed webhook.

2. On demand: GET /v1/analyses/{id}/exportCopy Anchor Link

Generates the file on the fly, with your API key, for any finished analysis whose results are still stored:

curl -OJ "https://api.constaia.com/v1/analyses/an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2/export?format=xlsx" \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

• format accepts json (default), csv, xlsx, xml, vcard or pdf.
• The response is the file with Content-Disposition: attachment; filename="an_….xlsx" (that is why curl -OJ saves it under its name).
• If the analysis hasn't finished: 409 analysis_not_completed. Wait for completed.
• If it was deleted or created with keep_results: false: 404 resource_missing.

Downloading from your codeCopy Anchor Link

import { writeFile } from "node:fs/promises";
import { Constaia, InvalidRequestError } from "@constaia/sdk";

const constaia = new Constaia();
const id = process.argv[2]!;

try {
  const res = await constaia.analyses.export(id, "xlsx");
  await writeFile(`${id}.xlsx`, Buffer.from(await res.arrayBuffer()));
  console.log(`Saved ${id}.xlsx`);
} catch (err) {
  if (err instanceof InvalidRequestError && err.code === "analysis_not_completed") {
    console.error("The analysis hasn't finished yet.");
  } else {
    throw err;
  }
}

To download a signed URL from exports you need neither the SDK nor the key: a plain GET is enough.

curl -o invoice.xlsx "https://api.constaia.com/v1/files/exp_01J9Z…?expires=1790244002&sig=…"

Combined batch exportCopy Anchor Link

In a batch, options.export applies to the batch: when every document has finished, Constaia generates a single file per format with one row per document (extracted fields and verdict). The URLs arrive in the batch object's exports and in the batch.completed webhook:

curl https://api.constaia.com/v1/batches \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F "files[]=@invoice-1.pdf" \
  -F "files[]=@invoice-2.pdf" \
  -F 'options={"expect":"invoice","export":["xlsx"]}'

{
  "id": "bat_01J9Z…",
  "object": "batch",
  "status": "completed",
  "total": 2,
  "exports": { "xlsx": "https://api.constaia.com/v1/files/exp_01J9Z…?expires=…&sig=…" }
}

It is the easiest way to turn a pile of invoices into a spreadsheet. Full guide: invoices to Excel.

PrivacyCopy Anchor Link

Exported files are stored encrypted, like documents, and are deleted when you delete the analysis (DELETE /v1/analyses/{id}). Signed links expire after 24 hours. More in storage and privacy.

Next stepsCopy Anchor Link