Quickstart
A first POST /analyze call and what comes back
Aletheia takes the documents of one case, runs deterministic fraud and forgery checks, and returns a verdict with named-rule evidence. One call is enough to see it work.
1. Credentials
There is no self-service signup. IDCanopy provisions your tenant API key
(fsk_<prefix>_<secret>) at onboarding, see Sandbox.
Base URLs are in Environments; the production host is
https://aletheia.api-umbrella.io, other environments carry a suffix (-sbx, -test, -dev).
export ALETHEIA_BASE_URL=https://aletheia.api-umbrella.io
export TOKEN=fsk_... # from onboarding, never commit it2. Submit a case
POST /analyze is stateless and synchronous: 1 to 15 files in the repeated files field, an
optional applicant_id label, an optional case_meta JSON string. The document type is inferred
from the filename (passport, kontoauszug, gz, ...), see
Submitting a case.
curl -sS -X POST "$ALETHEIA_BASE_URL/analyze" \
-H "Authorization: Bearer $TOKEN" \
-F "files=@applicant_passport.pdf" \
-F "files=@applicant_kontoauszug.pdf" \
-F "files=@applicant_gz_2025-12.pdf" \
-F "applicant_id=CASE-2026-000123"A case takes roughly a minute per document; keep the client timeout generous (120 s or more).
3. Read the result
200 OK with a ForensicResult (abridged):
{
"applicant_id": "CASE-2026-000123",
"case_type": "account_application",
"verdict": {
"verdict": "ESCALATE",
"reason_codes": ["AML2", "F13"],
"override_rules_fired": ["F13"],
"verdict_explanation": "Rule F13: verdict floor ESCALATE triggered by 2 finding(s) at HIGH+"
},
"findings": [
{
"check_id": "sv_nr_invalid",
"check_category": "payslip",
"severity": "HIGH",
"summary": "SV-Nr validation failed: check digit mismatch",
"evidence_quote": "SV-Nr 1234 010180",
"source_document_id": "applicant_gz_2025-12",
"message": {
"what": "The Austrian social-security number (SV-Nr) is not a valid number.",
"what_to_do": "Confirm the number against the source document; a genuine invalid number should be queried with the applicant."
}
}
],
"advisory_score": 42,
"advisory_band": "REVIEW",
"analysis_ts": "2026-06-02T08:42:11Z",
"checker_version": "0.5.1-phase4"
}verdict.verdictdrives the decision:REJECT,ESCALATE,PENDING,CONDITIONALorPASS, in that order of severity. Every verdict traces to the rules inoverride_rules_firedandreason_codes.findings[]are the evidence.check_idvalues are stable and listed in check-catalog.json;messageis the operator text from the message catalogue.advisory_score(0 to 100) andadvisory_bandare informational and never drive the verdict.
Errors come back as {"detail": "..."}: 401 for a missing or invalid key, 413 over the size
limits, 422 for validation, 429 with Retry-After when rate-limited. See
Agents for the full table.
Next
- Documents arriving over time, ZIP bundles, callbacks instead of polling: Submitting a case.
- Grant settlements and other typed cases: Case types.
- Driving Aletheia from an AI agent: MCP server.
- Every operation and schema: Reference.