Introduction

Constaia is an API to validate, classify and extract data from documents with AI. It is built for registration forms, customer onboarding, licences, case files and any flow where someone uploads a document and you have to decide whether it is acceptable.

The question it answersCopy Anchor Link

Most document APIs give you text or fields. Constaia answers a different question:

Is this document a valid X?

You say what you expect (expect: "es_dni") and which rules it must meet (checks: not expired, holder, maximum age, signature, amount…). Constaia returns one of three verdicts:

Each verdict comes with reasons (reasons): a stable code for your logic and a localised message to show the user. Details in Verdicts and reasons.

A minimal exampleCopy 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"}'

{
  "id": "an_01J...",
  "object": "analysis",
  "status": "completed",
  "document": { "type": "es_dni", "label": "DNI (España)", "confidence": 0.97, "side": "both", "country": "ESP" },
  "verdict": {
    "expected": ["es_dni"],
    "match": true,
    "status": "valid",
    "reasons": [
      { "code": "type_match", "severity": "info", "message": "El documento es DNI (España)." },
      { "code": "not_expired", "severity": "info", "message": "Vigente hasta el 12/03/2031." }
    ]
  },
  "checks": [
    { "code": "nif_check_digit", "passed": true, "message": "La letra del documento 12345678Z es correcta." }
  ],
  "warnings": []
}

Messages are in Spanish by default; send "language": "en" in the options to get them in English ("Valid until 12/03/2031."). With a test key (ck_test_...) you can run this call right now without spending credits: the result depends on the file name. See the quickstart.

What every analysis returnsCopy Anchor Link

• document: detected type from the catalogue, readable label, confidence, side and country.
• verdict: status (valid, invalid, review) and reasons. It is null if you don't send expect.
• fields: extracted data, each with value, confidence, validated and source (page and source rectangle). You can also pass your own JSON Schema in extract.
• checks: deterministic validations (NIF check letter, MRZ check digits, IBAN, invoice totals…) that do not depend on AI.
• warnings: quality or possible-tampering signals (blurry, glare, screen_photo_suspected…). They are signals, not proof of fraud.
• exports: signed links to JSON, CSV, XLSX, XML, vCard or PDF if you ask for them.
• usage: pages processed and credits consumed.

All concepts, summarised, in Key concepts.

European, with zero retention by defaultCopy Anchor Link

• Processing happens in the EU, with AI providers in European regions. See Storage and privacy and Data residency.
• By default storage is none: in a synchronous analysis the file is processed in memory and never written to any storage. If you need to keep it, choose temporary (with ttl_hours) or persistent.
• With keep_results: false the extracted data is not stored either: you get it once and that's it.
• Files that are stored are encrypted in the application (AES-256-GCM, per-account key) before reaching object storage in the EU.

What Constaia is notCopy Anchor Link

Constaia is not biometric KYC: it does not compare faces, does no liveness checks and does not query official registries. It checks that the document is the type you expect, that its data is consistent and that it meets your rules. Warnings about possible editing or screen photos are signals to decide whether to review, not fraud detection.

Next stepsCopy Anchor Link