Verdicts and reasons

The verdict answers one specific question: "is this document a valid X according to my rules?". It appears in verdict when you state what you expect with expect. Without expect, verdict is null and you only get the classification (document), the fields (fields), the deterministic checks (checks) and the signals (warnings).

The verdict objectCopy Anchor Link

"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." }
  ]
}

Each reason looks like this:

The three statusesCopy Anchor Link

The rule is mechanical and always the same:

if any reason has severity "error"      → invalid
else if any has severity "warning"      → review
else                                     → valid

error beats warning: an expired DNI that is also blurry is invalid, not review.

review is not an API failure. It means Constaia does not have enough information to decide safely, and a person should look at it or you should ask for another photo. See the human review guide.

Which reasons appearCopy Anchor Link

1. Type: always exactly one of type_match, type_mismatch or type_unknown.
2. Checks you asked for (and those on by default, such as not_expired for documents with an expiry date): one or more reasons each. Details in checks.
3. Type-specific rules: not_fit_for_sport (medical certificate saying "not fit"), has_records (criminal record certificates).
4. Failed deterministic checks: if an item in checks[] has passed: false, a reason with the same code and severity error is added. Passing checks only appear in checks[], not in reasons.
5. Quality and confidence: low_quality and low_confidence, with severity warning.
6. PDF: the electronic signature result (signature_valid, signature_invalid…) and edited_suspected when the metadata points to editing. See digital signatures in PDF.
7. Form I-9: i9_list (info) on US documents from lists A, B or C.

Reason code tableCopy Anchor Link

These codes are stable. We may add new codes without notice (see versioning): treat any unknown code according to its severity.

Same code, different severityCopy Anchor Link

The code tells you which rule was evaluated; the severity tells you how it went. A valid DNI and an expired one produce the same code:

{ "code": "not_expired", "severity": "info", "message": "Valid until 12/03/2031." }

{ "code": "not_expired", "severity": "error", "message": "Expired on 15/06/2020." }

So your code must always look at the code + severity pair, never just at whether the code is present.

Signals (warnings)Copy Anchor Link

warnings is a list of signals about the image or the document. They are not proof of fraud: they are hints to decide whether to ask for another photo or review by hand. Constaia is not biometric KYC and does no face matching.

The quality signals (low_quality, blurry, cropped, glare, screen_photo_suspected, photocopy_suspected, edited_suspected, multiple_documents) are summarised in a single low_quality reason with severity warning, so they push the verdict to review (unless there is an error). side_missing and language_mismatch appear in warnings but do not change the verdict on their own.

"verdict": {
  "expected": ["es_dni"],
  "match": true,
  "status": "review",
  "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." },
    { "code": "low_quality", "severity": "warning", "message": "Image quality is insufficient (blurry, low_quality)." }
  ]
},
"warnings": ["blurry", "low_quality"]

If the image is so bad that it is rejected before OCR, document is null, match is false, the only reason is low_quality (warning) and the analysis is not charged.

What to do with each verdictCopy Anchor Link

Also remember the analysis may not be finished: with async: true, or if it takes longer than 30 s, you get 202 with status: "queued" or "processing" and the result arrives by webhook.

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

const constaia = new Constaia(); // reads CONSTAIA_API_KEY

type Decision =
  | { action: "accept"; documentNumber: string | undefined }
  | { action: "reject"; errors: string[] }
  | { action: "review"; warnings: string[] }
  | { action: "pending"; id: string };

export async function checkDni(path: string, fullName: string): Promise<Decision> {
  const analysis = await constaia.analyze(await fromPath(path), {
    expect: "es_dni",
    checks: { holder: { fullName } },
    language: "en",
  });

  if (analysis.status !== "completed") {
    return { action: "pending", id: analysis.id }; // will arrive by webhook
  }

  const reasons = analysis.verdict?.reasons ?? [];
  switch (analysis.verdict?.status) {
    case "valid":
      return { action: "accept", documentNumber: analysis.fields.document_number?.value as string | undefined };
    case "invalid":
      return {
        action: "reject",
        errors: reasons.filter((r) => r.severity === "error").map((r) => r.message),
      };
    default:
      return {
        action: "review",
        warnings: reasons.filter((r) => r.severity === "warning").map((r) => r.message),
      };
  }
}

try {
  console.log(await checkDni("./dni_valid.jpg", "María García López"));
} catch (err) {
  if (err instanceof InvalidRequestError) console.error(err.code, err.param, err.message);
  else throw err;
}

Several accepted typesCopy Anchor Link

With expect as a list, match is true if the document is any of them. This is the usual setup for "identity document": DNI, NIE/TIE or passport.

{ "file_url": "https://example.com/nie.jpg", "expect": ["es_dni", "es_nie", "passport"], "language": "en" }

"document": { "type": "es_nie", "label": "Spanish foreigner ID (NIE / TIE)", "confidence": 0.97, "side": "both", "country": "ESP" },
"verdict": {
  "expected": ["es_dni", "es_nie", "passport"],
  "match": true,
  "status": "valid",
  "reasons": [
    { "code": "type_match", "severity": "info", "message": "The document is Spanish foreigner ID (NIE / TIE)." },
    { "code": "not_expired", "severity": "info", "message": "Valid until 30/11/2029." }
  ]
}

Checks are evaluated against the detected type, so look at document.type to know which field holds the number (document_number for DNI and passport, nie_number for NIE). You can look up the fields of each type with GET /v1/document-types/{type} or in the catalogue.

Without expect: verdict is nullCopy Anchor Link

If you don't send expect, Constaia classifies and extracts, but does not decide:

"document": { "type": "generic", "label": "Other document", "confidence": 0.64, "side": null, "country": null },
"verdict": null,
"checks": [],
"warnings": []

Use it when you don't know which document will be uploaded and want to route on document.type, or when you apply your own rules to fields. If you only need the type, POST /v1/classify costs 0.2 credits; its verdict only contains type_match or type_mismatch.

Next stepsCopy Anchor Link