POST /v1/analyze

POST https://api.constaia.com/v1/analyze takes a document, classifies it, extracts its fields and, if you tell it what you expect with expect, validates it and returns a valid, invalid or review verdict. It is the main endpoint of the API.

If you only need to know which document it is (for example, to route it), use POST /v1/classify, which costs 0.2 credits. For many documents at once, POST /v1/batches. If in doubt, see Which endpoint to use.

Sending the documentCopy Anchor Link

There are two ways to send the request. Any other Content-Type returns 415 unsupported_content_type.

1. multipart/form-dataCopy Anchor Link

curl https://api.constaia.com/v1/analyze \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F file=@dni_valid.jpg \
  -F 'options={"expect":"es_dni","checks":{"min_age_years":18}}'

Shortcut for quick tests: if you do not send options, you can pass expect as a form field, repeatable for several types:

curl https://api.constaia.com/v1/analyze \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F file=@nie.jpg -F expect=es_dni -F expect=es_nie -F expect=passport

If you send options, the loose expect field is ignored.

2. application/jsonCopy Anchor Link

With a public URL or with the file in base64:

curl https://api.constaia.com/v1/analyze \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/uploads/receipt.pdf",
    "options": {
      "expect": "payment_receipt",
      "checks": { "expected_amount": 45, "expected_reference": "INSCRIPCION 123" }
    }
  }'

curl https://api.constaia.com/v1/analyze \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"file_base64\": \"$(base64 < dni_valid.jpg | tr -d '\n')\",
    \"filename\": \"dni_valid.jpg\",
    \"expect\": \"es_dni\",
    \"language\": \"en\"
  }"

Use one of the two forms for options: if the body has options, root keys (other than file_url, file_base64 and filename) are not read.

Accepted filesCopy Anchor Link

• Formats: JPEG, PNG, WEBP, HEIC and PDF. The type is detected from the content (magic bytes), not the extension.
• Size: up to 20 MB (413 file_too_large).
• Pages: a PDF can have up to 30 pages in synchronous mode and up to 200 with async: true or inside a batch. Above that, 422 too_many_pages.
• A DNI with front and back can go in a single file (one image with both sides or a two-page PDF).
• In test mode the file name decides the simulated response, so mind filename.

OptionsCopy Anchor Link

Options are strict: an unknown key returns 422 invalid_parameter with param: "options.<key>".

Processing profileCopy Anchor Link

processing chooses which AI providers may touch the document in this request:

• sovereign: only providers headquartered and operated in the EU (a European or Constaia-hosted model, Mistral OCR in Paris and the local MRZ and PDF417 readers).
• standard: may also use Claude on AWS Bedrock (Frankfurt, eu-central-1) or Gemini on Google Vertex AI (EU region). Data is processed in EU regions, but AWS and Google are US-headquartered companies (US CLOUD Act exposure).
• If you do not send it, your account profile is used. If the requested profile is not available, the API answers 422 processing_unavailable with param: "options.processing".

The response always tells you what was used in the processing object. Details in Data residency.

ChecksCopy Anchor Link

checks is strict too. Each check only applies if the detected type has the relevant field (for example, generic has no expiry date). Which checks each type supports is listed in the checks array of GET /v1/document-types/{type}. Detailed explanation in Checks.

{
  "expect": ["es_dni", "es_nie", "passport"],
  "checks": {
    "min_age_years": 18,
    "holder": { "full_name": "María García López", "birth_date": "1990-05-14" }
  },
  "storage": "none",
  "metadata": { "registration_id": "123" },
  "language": "en"
}

Extracting fields with your own schemaCopy Anchor Link

Pass a JSON Schema in extract and fields will contain the fields of your schema. Useful with generic or when you only want a few fields. Each property's description guides the extraction.

{
  "expect": "generic",
  "extract": {
    "type": "object",
    "properties": {
      "club_name": { "type": "string", "description": "Name of the club issuing the document" },
      "member_name": { "type": "string", "description": "Member's full name" },
      "season": { "type": "string", "description": "Season, e.g. 2026-2027" }
    }
  },
  "checks": { "require_fields": ["club_name", "member_name"] }
}

Synchronous or asynchronousCopy Anchor Link

• By default the request waits for the result for up to 30 seconds and answers 200 with status: "completed" (or "failed").
• If the analysis takes longer than 30 s, the API answers 202 with the analysis in queued or processing. The work continues and the result arrives in the analysis.completed webhook; you can also poll GET /v1/analyses/{id}.
• With async: true the response is an immediate 202 with status: "queued". It allows PDFs of up to 200 pages.

Your code must always handle 202: check status before reading verdict or fields.

Response: the analysis objectCopy Anchor Link

{
  "id": "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2",
  "object": "analysis",
  "status": "completed",
  "livemode": false,
  "created_at": "2026-09-29T10:00:00Z",
  "completed_at": "2026-09-29T10:00:02Z",
  "file": { "name": "dni_valid.jpg", "mime_type": "image/jpeg", "pages": 1, "size_bytes": 482133 },
  "document": { "type": "es_dni", "label": "Spanish ID card (DNI)", "confidence": 0.97, "side": "both", "country": "ESP" },
  "verdict": {
    "expected": ["es_dni"],
    "match": true,
    "status": "valid",
    "reasons": [
      { "code": "type_match", "severity": "info", "message": "The document is Spanish ID card (DNI)." },
      { "code": "not_expired", "severity": "info", "message": "Valid until 12/03/2031." }
    ]
  },
  "fields": {
    "document_number": {
      "value": "12345678Z",
      "confidence": 0.99,
      "validated": true,
      "source": { "page": 1, "bbox": [0.61, 0.12, 0.83, 0.16] }
    }
  },
  "checks": [
    { "code": "nif_check_digit", "passed": true, "message": "The check letter of 12345678Z is correct." },
    { "code": "mrz_checksums", "passed": true, "message": "The MRZ check digits are correct." },
    { "code": "mrz_matches_visual", "passed": true, "message": "The MRZ matches the printed data." }
  ],
  "warnings": [],
  "signature": null,
  "exports": {},
  "storage": { "mode": "none", "file_deleted_at": "2026-09-29T10:00:02Z", "expires_at": null },
  "processing": {
    "profile": "sovereign",
    "region": "eu",
    "mode": "vlm",
    "providers": [{ "name": "mock", "region": "local", "role": "llm", "model": "mock-llm-1" }]
  },
  "usage": { "credits": 0, "pages": 1 },
  "metadata": {}
}

In the example, fields is trimmed to one field. A DNI also returns first_name, last_name_1, last_name_2, sex, nationality, birth_date, expiry_date, issue_date, support_number, address, birth_place, parents and mrz, each with the same structure.

The processing objectCopy Anchor Link

It tells you which profile was applied and which providers touched the document, so you can prove it in an audit:

{
  "profile": "sovereign",
  "region": "eu",
  "mode": "vlm",
  "providers": [
    { "name": "tesseract", "region": "local", "role": "local", "model": "mrz" },
    { "name": "openai_compat", "region": "de-fra", "role": "llm", "model": "mistral-small-3.2" }
  ]
}

In test mode the only provider is mock. While the analysis is queued, processing may be null.

The signature objectCopy Anchor Link

PDF only. Constaia verifies the PAdES signature of the original file (integrity, certificate chain and later changes) at no extra cost:

{
  "status": "valid",
  "reasons": ["signature_valid"],
  "signer": "SELLO ELECTRONICO DEL MINISTERIO DE JUSTICIA",
  "issuer": "AC Sector Público",
  "signed_at": "2026-09-28T09:14:03Z",
  "trusted": true,
  "trust_anchor": "AC RAIZ FNMT-RCM",
  "signatures": 1
}

status is valid, invalid, missing, modified or untrusted. What each status guarantees and how to require it with require_valid_signature: Digital signatures in PDF.

Reasons (verdict.reasons[].code)Copy Anchor Link

The same code can come with severity info (passes), warning (leads to review) or error (leads to invalid). For example, an expired DNI returns { "code": "not_expired", "severity": "error", "message": "Expired on 15/06/2020." } (with language: "en"; the default language is Spanish).

The first reason is always about the type:

• type_match (info): the detected type is in expect.
• type_mismatch (error, leads to invalid): a catalogue type is recognised, but it is none of the expected ones.
• type_unknown (warning, leads to review): the document could not be identified (type generic) or classification confidence is below 0.5.

Full list of codes: type_match, type_mismatch, type_unknown, not_expired, max_age_days, age, min_age_years, max_age_years, holder, required_field_missing, require_signature, require_stamp, expected_amount, expected_iban, expected_reference, not_fit_for_sport, has_records, low_quality, low_confidence, plus the code of any deterministic validator that fails (usually with severity error).

Also:

• PDF signature: signature_valid (info), signature_invalid (always error), signature_missing, document_modified_after_signing and untrusted_signer. Without require_valid_signature the last three are warning (and signature_missing only appears for types that are usually signed); with it, they are error. See Digital signatures in PDF.
• PDF metadata: edited_suspected (warning): the PDF was produced by a known editor, its modification date is much later than its creation date, or it changed after being signed.
• Form I-9 (US): i9_list (info) tells you which list (A, B or C) the document belongs to. See US documents.

Validators (checks[].code)Copy Anchor Link

Warnings (warnings)Copy Anchor Link

Constaia is not a biometric KYC and does no face matching.

Status codes and errorsCopy Anchor Link

Error format and handling in Errors. To retry without double charges, send the Idempotency-Key header (Idempotency).

Complete examplesCopy Anchor Link

curl https://api.constaia.com/v1/analyze \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Idempotency-Key: registration-123-dni" \
  -F file=@dni_valid.jpg \
  -F 'options={
    "expect": ["es_dni", "es_nie", "passport"],
    "checks": { "min_age_years": 18, "holder": { "full_name": "María García López" } },
    "metadata": { "registration_id": "123" },
    "language": "en"
  }'

JSON with file_url and file_base64Copy Anchor Link

import { readFile } from "node:fs/promises";
import { Constaia } from "@constaia/sdk";

const constaia = new Constaia();

const fromUrl = await constaia.analyze(
  { fileUrl: "https://example.com/uploads/receipt.pdf" },
  { expect: "payment_receipt", checks: { expectedAmount: 45, expectedReference: "INSCRIPCION 123" } },
);

const fromBase64 = await constaia.analyze(
  { base64: (await readFile("./invoice.pdf")).toString("base64"), filename: "invoice.pdf" },
  { expect: "invoice", export: ["xlsx"] },
);

console.log(fromUrl.verdict?.status, fromBase64.exports.xlsx);

Next stepsCopy Anchor Link