Document types

Every document you analyse is classified into a type. The type identifier (es_dni, payment_receipt, invoice…) is what you send in expect and what you receive in document.type. Each type defines:

• a field template: what extract: true returns in fields;
• deterministic validators that run whenever the document allows it: NIF/NIE check letter, MRZ check digits, national identifiers (CPF, CURP, PESEL, SSN…), IBAN, totals, CSV format, the PDF417 barcode on US licenses and the electronic signature of PDFs;
• the checks that make sense for it: expiry on a DNI, issue age on a certificate, amount on a receipt.

The catalogue has 167 types: identity documents from the 30 EU/EEA countries and Switzerland, driving licences, residence permits, Latin America, the United States and Canada, certificates, tax, payslips, invoices… The source of truth is GET /v1/document-types: public, no key needed, filterable by country (country), category (category) or text (q) and always up to date. To see each type in more detail, open the full catalogue.

CategoriesCopy Anchor Link

CatalogueCopy Anchor Link

Accepting several types with expectCopy Anchor Link

Often more than one document is fine: "DNI, NIE or passport". Pass a list in expect (up to 20 types). The verdict is valid if the document is any of them and passes the checks.

{
  "expect": ["es_dni", "es_nie", "passport", "eu_id_card"],
  "checks": { "min_age_years": 18, "holder": { "full_name": "María García López" } }
}

• The detected type arrives in document.type and verdict.expected repeats your list.
• If a catalogue type is recognised that is not in the list, the verdict is invalid with the type_mismatch reason.
• If the document cannot be identified (generic) or classification confidence is below 0.5, the reason is type_unknown and the verdict review.

Each check only applies if the detected type has the relevant field: min_age_years on a DNI, max_age_days on a certificate, expected_amount on a receipt. If you mix types, pick checks that make sense for all of them or branch on document.type. Which checks each type supports is given by its checks list in GET /v1/document-types/{type}.

import { Constaia } from "@constaia/sdk";
import { fromPath } from "@constaia/sdk/node";

const constaia = new Constaia();

const analysis = await constaia.analyze(await fromPath("./nie.jpg"), {
  expect: ["es_dni", "es_nie", "passport"],
  checks: { minAgeYears: 18, holder: { fullName: "Anna Kowalska" } },
});

switch (analysis.document?.type) {
  case "es_dni":
    console.log(analysis.fields.document_number?.value);
    break;
  case "es_nie":
    console.log(analysis.fields.nie_number?.value);
    break;
  case "passport":
    console.log(analysis.fields.document_number?.value, analysis.fields.nationality?.value);
    break;
}
console.log(analysis.verdict?.status);

In test mode, a file named nie.jpg returns a valid NIE for ANNA KOWALSKA.

generic with your own schemaCopy Anchor Link

If your document is not in the catalogue (a club authorisation, an internal form, an unusual certificate), analyse it with generic and describe the fields with a JSON Schema in extract:

{
  "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" },
      "signed": { "type": "boolean", "description": "Whether the document is signed" }
    }
  },
  "checks": { "require_fields": ["club_name", "member_name"] }
}

Fields come back in fields with value, confidence and position, just like catalogue types. generic has no deterministic validators and no expiry: the useful checks are require_fields and max_age_days. Result quality depends on how clear your schema's description texts are. More in POST /v1/analyze.

You can also pass your own schema with a catalogue type to keep only some fields: start from the schema returned by GET /v1/document-types/{type}.

New types in your codeCopy Anchor Link

The catalogue grows. Build your integration so it does not break if document.type carries a type it does not know: treat it as "other document" and send it to review. If you validate your configuration at startup, do it against GET /v1/document-types, not against a hard-coded list.

Next stepsCopy Anchor Link