Human review
What to do with the review verdict. Why it happens, receiving it by webhook, building a review queue, recording the decision and asking for a new photo.
The Revisar verdict means Constaia can't decide with confidence: the photo is blurry, a field can't be read or confidence is low. It isn't a rejection. Most of the time the document is fine and all it takes is a person looking at it, or asking for another photo.
This guide builds that loop in your application: detect review, put it in a queue, show it to a reviewer, store the
decision and, if needed, ask for a new document. Your team can also review directly in the
dashboard. If you'd rather have your backend use Constaia's queue (list pending reviews,
download the original and record the decision through the API), go to
Human review from your backend.
When review happens
The verdict is review when there is at least one reason with severity: "warning" and none with error:
code with warning | Cause |
|---|---|
low_quality | There are quality or authenticity warnings in warnings (see the table below). |
low_confidence | Confidence in the type or key fields is low: "Confidence is low (0.62); a manual review is recommended.". |
type_unknown | The document type could not be identified. |
not_expired, max_age_days, age | You asked for the check but the expiry, issue or birth date can't be found. |
holder | You asked to compare a holder field and it couldn't be read. |
If the image is so poor that it's rejected before OCR, the analysis ends with document: null, review and the
low_quality reason. Those analyses aren't charged.
Warnings that can appear in warnings:
| Code | Meaning |
|---|---|
low_quality | Overall low quality. |
blurry | Blurry image. |
cropped | The document is cropped. |
glare | Glare hides data. |
screen_photo_suspected | Possible photo of a screen. |
photocopy_suspected | Possible photocopy. |
edited_suspected | Possible digital edit. |
multiple_documents | More than one document in the file. |
side_missing | One side is missing. |
language_mismatch | The language is not the expected one for the type. |
Warnings are signals, not proof of authenticity.
Warnings are signals, not proof of fraud. Constaia is not biometric KYC and does no face matching.
Step 1: decide where the reviewer gets the document
A reviewer needs to see the document. You have three options:
- Let Constaia keep it as long as needed (what happens by default, with
storage: "review"): the original is stored encrypted only if the analysis needs review, and deleted once decided (24 hours later, adjustable) or after 30 days if nobody decides. Your backend downloads it withGET /v1/analyses/{id}/fileor shows the analysis signedfile_url(expires after 15 minutes). See Human review from your backend. - Keep your own copy only as long as needed: when you receive the file, store it encrypted in your storage. If the
verdict is
validorinvalid, delete it right away; if it'sreview, keep it until the reviewer decides. In that case you can sendstorage: "none"so Constaia never stores the document. - Store nothing and ask for another photo: if you don't want to hold documents, on
reviewask for a new document straight away (step 5). It's the simplest option when the only reason islow_quality.
Step 2: receive the review
In a synchronous analysis review comes in the response itself. Constaia also sends the analysis.review_required
webhook:
| Source | Events you receive |
|---|---|
Single analysis (synchronous or async) | analysis.completed and analysis.review_required |
| Document in a batch | Only analysis.review_required (and batch.completed at the end of the batch) |
If you handle both the response and the webhooks, create the queue item with the analysis id as a unique key so it
isn't duplicated. Use metadata to know which record in your system it belongs to.
CREATE TABLE review_queue (
analysis_id text PRIMARY KEY,
registration_id text NOT NULL,
reasons jsonb NOT NULL,
warnings jsonb NOT NULL,
file_path text,
status text NOT NULL DEFAULT 'pending', -- pending | approved | rejected | new_document_requested
reviewer text,
decided_at timestamptz,
note text,
created_at timestamptz NOT NULL DEFAULT now()
);import express from "express";
import { Constaia, WebhookVerificationError } from "@constaia/sdk";
import { sql } from "./db.js";
const app = express();
const constaia = new Constaia();
app.post("/webhooks/constaia", express.raw({ type: "application/json" }), async (req, res) => {
let event;
try {
event = await constaia.webhooks.verify(req.body, req.headers, process.env.CONSTAIA_WEBHOOK_SECRET);
} catch (err) {
if (err instanceof WebhookVerificationError) return res.status(400).send("invalid signature");
throw err;
}
if (event.type === "analysis.review_required") {
const analysis = event.data;
await sql`
INSERT INTO review_queue (analysis_id, registration_id, reasons, warnings)
VALUES (${analysis.id}, ${analysis.metadata.registration_id},
${JSON.stringify(analysis.verdict.reasons.filter((r) => r.severity !== "info"))},
${JSON.stringify(analysis.warnings)})
ON CONFLICT (analysis_id) DO NOTHING`;
}
res.sendStatus(200);
});
app.listen(3000);Step 3: show the document to the reviewer
On the review screen show:
- The document (step 1): the original kept by Constaia or your copy.
- The reasons with
warning: they explain why it wasn't decided automatically. They come in thelanguageyou asked for. - The extracted fields and their
confidence, so the reviewer can compare with the image. If you keep results (keep_results: true, the default), read them when needed withGET /v1/analyses/{id}; otherwise, store in the queue the fields the reviewer has to see. fields.<field>.source.bbox(normalised 0–1 coordinates on pagesource.page), in case you want to highlight where each value is on the image. It can benull.
Step 4: record the decision
Store who decided, when, what and why, and link it to the analysis_id. If you also want the decision recorded at
Constaia (on the analysis, in the dashboard and in the audit log), send it with POST /v1/analyses/{id}/review:
verdict.final_status becomes valid or invalid, you receive the analysis.reviewed webhook and the original is
deleted after the post-decision window. See Human review from your backend.
In your own system, for example:
UPDATE review_queue
SET status = 'approved', reviewer = 'ana@club.example', decided_at = now(),
note = 'ID readable on the copy; data matches the form'
WHERE analysis_id = 'an_01J...';Then apply the consequence (confirm the registration, reject it) and delete your copy of the document, if you had one.
If you no longer need the results at Constaia, delete them with DELETE /v1/analyses/{id}.
Step 5: ask for a new photo
When the reason is quality (low_quality) or the reviewer can't read the document, ask for another one. Send the
person a link to your upload page (with the widget, which flags blurry, dark or low-resolution photos
before sending) and analyze again. The new analysis has a different id: store its link to the previous one and mark
the queue item as new_document_requested.
Tips you can show depending on the warning: blurry (hold the phone steady and focus), glare (avoid reflections, no
flash), cropped (all four corners visible), side_missing (upload both sides), screen_photo_suspected or
photocopy_suspected (photograph the original document).
Test it
With a ck_test_… key, an image named blurry.jpg (or containing blur or borros) returns the dni_valid ID with
the blurry and low_quality warnings (messages in Spanish, the default language):
{
"verdict": {
"expected": ["es_dni"],
"match": true,
"status": "review",
"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." },
{ "code": "low_quality", "severity": "warning", "message": "La calidad de la imagen es insuficiente (blurry, low_quality)." }
]
},
"warnings": ["blurry", "low_quality"]
}With "language": "en" the last message reads "Image quality is insufficient (blurry, low_quality).". As a single
analysis you receive analysis.completed and analysis.review_required; inside a batch, only
analysis.review_required. From the dashboard you can also send a test event to your endpoint. More in
Test mode.
Next steps
Human review from your backend
List pending reviews, download the original and decide through the API.
Verdicts
How valid, invalid and review are computed.
Webhooks
analysis.review_required, signature and retries.
Widget
Quality check before sending the photo.
ID in sign-ups
The full flow the review fits into.
Analyze without storing
Data minimisation (GDPR) with Constaia. Analyze documents without keeping the file or the extracted data using storage none and keep_results false.
Human review from your backend
Bring human review into your own application with the API. Get pending reviews, download the original document, record the decision and apply the final result.