Dossiers

A dossier (dos_…) groups the documents of one person or procedure (the ID, the medical certificate and the payment receipt of a registration, for example) and computes an overall verdict: whether everything is there, whether something fails or whether it needs a review. It also checks that every document belongs to the same holder and that their dates are consistent.

Every route uses a secret key (ck_test_… or ck_live_…) from your backend and only sees the dossiers of the key's mode. In the dashboard they are under Dossiers.

Create a dossierCopy Anchor Link

POST /v1/dossiers
Content-Type: application/json

A dossier without requirements (or template) works too: it accepts any document, and the verdict is computed with all the ones you add.

curl https://api.constaia.com/v1/dossiers \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "registration-4821",
    "metadata": { "registration_id": "4821" },
    "requirements": [
      { "key": "id_card", "label": "ID card", "expect": ["es_dni", "es_nie"], "checks": { "not_expired": true } },
      { "key": "medical", "label": "Medical certificate", "expect": "medical_certificate_sport", "checks": { "max_age_days": 180 } }
    ]
  }'

Answers 201 with the dossier object, with verdict.status: "incomplete" until the documents arrive. A repeated key returns 422 duplicate_document_key; an invalid expect or check, 422 invalid_parameter with param: "requirements.<i>.<field>".

Add documentsCopy Anchor Link

POST /v1/dossiers/{id}/documents

There are two ways:

Answers 200 with the updated dossier.

# A file, for a given requirement
curl https://api.constaia.com/v1/dossiers/dos_01J9Z8Q3K4M5N6P7Q8R9S0T1V2/documents \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F "file=@dni.jpg" \
  -F "requirement_key=id_card"

# An analysis you already had
curl https://api.constaia.com/v1/dossiers/dos_01J9Z8Q3K4M5N6P7Q8R9S0T1V2/documents \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "analysis_id": "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V3", "requirement_key": "medical" }'

Which requirement it fills. If you send requirement_key, that one (if it doesn't exist: 422 invalid_document_key). Otherwise:

• with a file and a single requirement, that one; with several, it's analysed accepting the union of their expect (without their checks) and assigned to the first requirement with no document whose expect includes the detected type;
• with analysis_id, the analysis's requirement if it came from a link with the same key or, otherwise, as above according to its type;
• if no requirement fits, it stays as a loose document: it covers no requirement, but counts for the cross-document checks.

You can add several documents to the same requirement (a new photo after a rejection, for example). The latest one counts; if the latest failed, the latest one that completed.

The dossier objectCopy Anchor Link

{
  "id": "dos_01J9Z8Q3K4M5N6P7Q8R9S0T1V2",
  "object": "dossier",
  "livemode": false,
  "reference": "registration-4821",
  "template": null,
  "verification_link_id": null,
  "metadata": { "registration_id": "4821" },
  "requirements": [
    { "key": "id_card", "label": "ID card", "expect": ["es_dni", "es_nie"], "checks": { "not_expired": true }, "status": "valid", "analysis_id": "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V3" },
    { "key": "medical", "label": "Medical certificate", "expect": ["medical_certificate_sport"], "checks": { "max_age_days": 180 }, "status": "missing", "analysis_id": null }
  ],
  "documents": [
    { "analysis_id": "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V3", "requirement_key": "id_card", "type": "es_dni", "file_name": "dni.jpg", "status": "completed", "verdict_status": "valid", "final_status": "valid", "created_at": "2026-09-30T10:02:11Z" }
  ],
  "verdict": {
    "status": "incomplete",
    "reasons": [
      { "code": "requirement_missing", "severity": "warning", "message": "The document “Medical certificate” is missing.", "requirement_key": "medical" }
    ],
    "checks": [
      { "code": "same_holder", "passed": null, "severity": "warning", "message": "There isn't enough data to check that all documents belong to the same person.", "analyses": ["an_01J9Z8Q3K4M5N6P7Q8R9S0T1V3"] },
      { "code": "dates_consistent", "passed": true, "severity": "info", "message": "The dates on the documents are consistent.", "analyses": ["an_01J9Z8Q3K4M5N6P7Q8R9S0T1V3"] }
    ]
  },
  "holder": { "name": "MARÍA GARCÍA LÓPEZ", "document_number": "12345678Z", "birth_date": "1990-04-12" },
  "created_at": "2026-09-30T10:00:00Z",
  "updated_at": "2026-09-30T10:02:12Z"
}

Messages in reasons and checks follow the Accept-Language header (es, en, pt, fr).

Overall verdictCopy Anchor Link

Each requirement takes the status of its analysis. If a person reviewed the analysis, their decision counts (final_status); if it's waiting for review, or has no verdict, it counts as review. The dossier:

Without requirements, each added document counts as a requirement (and with no document at all, incomplete with the reason no_documents). The per-requirement reasons are requirement_missing, requirement_processing, requirement_failed, requirement_invalid and requirement_review.

The verdict is recomputed automatically when an analysis in the dossier finishes or when a person decides its review (in the dashboard or with POST /v1/analyses/{id}/review). Dossiers have no webhook of their own: call GET /v1/dossiers/{id} when you receive the document's analysis.completed or analysis.reviewed, or use a verification link and its verification_link.completed event.

Cross-document checksCopy Anchor Link

Only completed analyses count (the one that counts for each requirement and the loose documents). Values masked with mask_fields are not compared.

List, retrieve and deleteCopy Anchor Link

curl -G https://api.constaia.com/v1/dossiers \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  --data-urlencode "verdict=review" \
  --data-urlencode "metadata[registration_id]=4821"

GET /v1/dossiers/{id} returns the object. DELETE /v1/dossiers/{id} returns { "id": "dos_…", "object": "dossier", "deleted": true } and doesn't delete the analyses (for that, see deletion by metadata). A dossier from another mode, or one that doesn't exist, returns 404 resource_missing.

SDKsCopy Anchor Link

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

const constaia = new Constaia();

const dossier = await constaia.dossiers.create({
  reference: "registration-4821",
  requirements: [
    { key: "id_card", expect: ["es_dni", "es_nie"] },
    { key: "medical", expect: "medical_certificate_sport", checks: { maxAgeDays: 180 } },
  ],
});

await constaia.dossiers.addDocument(dossier.id, await fromPath("dni.jpg"), { requirementKey: "id_card" });
const updated = await constaia.dossiers.addDocument(
  dossier.id,
  { analysisId: "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V3" },
  { requirementKey: "medical" },
);

console.log(updated.verdict.status); // complete_valid | incomplete | invalid | review

ErrorsCopy Anchor Link

Next stepsCopy Anchor Link