POST /v1/classify

POST https://api.constaia.com/v1/classify answers a single question: which document is this. It does not extract fields or run checks, and it costs 0.2 credits per document, whatever its page count (0 in test mode).

Use it when you receive documents without knowing what they are (a mailbox, a shared folder, a form with a single "attach your documents" field) and need to route them: decide which queue each one goes to, or which expect and checks to apply next in POST /v1/analyze. If you already know which document you expect, call analyze with expect directly: you save one call.

RequestCopy Anchor Link

It accepts exactly the same inputs as POST /v1/analyze: multipart/form-data with file and options, or JSON with file_url or file_base64 + filename. Same formats, same 20 MB limit and the same -F expect=… shortcut.

Options are validated with the same strict schema. Those that have an effect on a classification are:

curl https://api.constaia.com/v1/classify \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F file=@dni_valid.jpg \
  -F 'options={"expect":["es_dni","es_nie","passport"],"language":"en"}'

Response: the classification objectCopy Anchor Link

{
  "id": "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2",
  "object": "classification",
  "status": "completed",
  "livemode": false,
  "created_at": "2026-09-29T10:00:00Z",
  "completed_at": "2026-09-29T10:00:01Z",
  "file": { "name": "dni_valid.jpg", "mime_type": "image/jpeg", "pages": 1, "size_bytes": 482133 },
  "document": { "type": "es_dni", "label": "Spanish ID card (DNI)", "confidence": 0.97 },
  "candidates": [{ "type": "es_dni", "confidence": 0.97 }],
  "verdict": {
    "expected": ["es_dni", "es_nie", "passport"],
    "match": true,
    "status": "valid",
    "reasons": [{ "code": "type_match", "severity": "info", "message": "The document is Spanish ID card (DNI)." }]
  },
  "warnings": [],
  "usage": { "credits": 0, "pages": 1 },
  "metadata": {}
}

A classify verdict of valid only says the type is the expected one. It does not check expiry, holder or any other rule: that is what analyze is for.

Like analyze, it can answer 202 if it goes asynchronous; in that case the result arrives in the analysis.completed webhook with data.object: "classification". Errors are the same as in analyze.

Pattern: classify, then analyseCopy Anchor Link

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

const constaia = new Constaia();

const checksByType: Record<string, Checks> = {
  payment_receipt: { expectedAmount: 45, expectedReference: "INSCRIPCION 123" },
  medical_certificate_sport: { maxAgeDays: 365, requireSignature: true },
  invoice: {},
};

const file = await fromPath("./attachment.pdf");
const classification = await constaia.classify(file, { expect: Object.keys(checksByType) });

const type = classification.document?.type;
if (classification.verdict?.status !== "valid" || !type) {
  console.log("Send to manual review:", classification.candidates);
} else {
  const analysis = await constaia.analyze(file, { expect: type, checks: checksByType[type] });
  console.log(type, analysis.verdict?.status);
}

With this pattern you pay an extra 0.2 credits per document. If your documents are always of a few types, it is usually cheaper to call analyze directly with expect as a list and branch on document.type, as explained in Document types.

Next stepsCopy Anchor Link