Submitting a case
Four ways to get a case package into Aletheia, plus the outbound webhook
A case package is the documents for one applicant, typically an ID, a bank statement, one or
more payslips, sometimes a pension notice. Aletheia accepts case packages four ways. All four
converge on the same deterministic engine and produce the same ForensicResult schema; auth and
error model (ProblemDetails) are identical across them.
| Path | Direction | Sync? | Use when |
|---|---|---|---|
(a) Stateless POST /analyze | client to us, push | sync | one-shot integrations, demos |
| (b) Stateful v1 lifecycle | client to us, push | async-capable | uploads over time, separated audit, async batch |
| (c) ZIP upload | client to us, push | async (submit + poll) | one signed bundle per case |
| (d) Outbound result webhook | us to client, push | n/a | register a callback URL, we POST the verdict on completion |
Case types. Everything on this page describes the default case type,
account_application(one applicant's documents). For other case types, such asgrant_settlement(an application plus cost items made of invoice, payment proof and proof of service), send the optionalcase_type,manifestandmaster_datafields on the same paths. See Case types.
Recommended default: push to us (paths a, b, c) plus register a callback (path d) for async delivery. You do not need to host your documents on a public URL, Aletheia accepts uploads directly.
An inbound URL-fetch option also exists (you host documents at HTTPS URLs and Aletheia fetches them), see below. It is not recommended for new integrations; it puts document hosting, allowlisting, and availability on you. It is offered only where an existing pipeline already serves documents that way.
1. Stateless POST /analyze
One synchronous request, returns the verdict. The simplest integration path.
The result is returned in the same HTTP request. No job polling is needed for this path. Errors return an HTTP error response instead.
Required headers: Authorization: Bearer <token> (your tenant API key, fsk_<prefix>_<secret>);
X-Tenant-ID (Mode B only, optional; ignored when the tenant comes from the key);
Content-Type: multipart/form-data (set by curl and HTTP clients).
Multipart body:
| Field | Required | Description |
|---|---|---|
files | yes | 1-15 files, repeat the field name per file. PDF, JPG, PNG, HEIC, TIFF. Max 20 MB each, 50 MB total. |
applicant_id | no | Caller-supplied label, echoed in the response |
case_meta | no | JSON string of arbitrary metadata, logged in the audit trail |
case_type, manifest, master_data | no | Typed case types only, manifest and master_data as JSON strings; see Case types |
There is no per-doc-type multipart field. All files go into files=. Document type is inferred
from the filename stem (case-insensitive):
| Type detected | Filename contains |
|---|---|
identity | passport, reisepass, ausweis, id, identity, rp, bg, fs, pa, personalausweis, führerschein, fuhrerschein |
payslip | payslip, gehaltszettel, gz, lohnzettel, salary |
bank_statement | bank, kaz, kontoauszug, statement, konto |
pensionsbescheid | pensionsbescheid, leistungsbescheid |
Filenames that match nothing get an unrecognized_document_type HIGH finding and the rest of the
case still processes.
curl -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-11.pdf" \
-F "files=@applicant_gz_2025-12.pdf" \
-F "applicant_id=CASE-2026-000123" \
-F 'case_meta={"source":"manual"}'Success, 200 OK. A ForensicResult. Shortened; the full schema is in the
reference:
{
"applicant_id": "CASE-2026-000123",
"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_gehaltszettel"
}
],
"advisory_score": 42,
"advisory_band": "REVIEW",
"analysis_ts": "2026-06-02T08:42:11Z",
"checker_version": "0.5.1-phase4"
}verdict.verdict drives the decision: REJECT, ESCALATE, PENDING, CONDITIONAL or PASS.
advisory_score and advisory_band (HIGH_RISK, REVIEW, LOW_RISK) are informational and do
not drive the verdict.
Errors. ProblemDetails, with trace_id on 5xx:
{ "detail": "At least one document file is required." }Status codes: 400 (no file uploaded), 401 (no or invalid bearer), 413 (body, file count or
file size over the limit), 422 (validation; FastAPI's detail is then a list of field errors),
429 (rate-limited, Retry-After header), 500 (usually {"detail": "internal server error"};
on /analyze the body also carries a trace_id, quote it in support requests).
Pending verification: for
500on/analyze, the Aletheia team's guide saysdetailcan be an object carryingtrace_idanderror_code, and that/analyze/reportcarries atrace_idtoo; the specification'sProblemDetailshasdetailas a string withtrace_idas a sibling field, present on/analyze5xx only. The Aletheia team is confirming the live shape.
2. Stateful v1 lifecycle
Same upload mechanics, split into steps. Useful when documents arrive over time or when you want to fetch findings separately.
The individual applicant analysis is synchronous. The separate async batch variant uses a job ID and polling; it is not shown here.
Step 1, create the applicant: POST /v1/applicants, JSON body
{"applicant_id": "CASE-2026-000123", "case_meta": {"source": "manual"}}.
Returns 201:
{ "applicant_id": "CASE-2026-000123", "tenant_id": "your-tenant", "created_at": "2026-06-02T08:40:00Z" }Step 2, upload documents (one or many calls): POST /v1/applicants/{applicant_id}/documents,
multipart, the same repeated files= field and filename rules as path 1. Returns 201:
{
"documents": [
{ "document_id": "doc_01", "filename": "applicant_passport.pdf", "byte_size": 482113, "content_sha256": "9f2c...e1" }
]
}Step 3, run analysis: POST /v1/applicants/{applicant_id}/analyze, body {}. Returns 200
with a ForensicResult, the same shape as path 1.
Later: GET /v1/applicants/{applicant_id}/findings returns the findings.
A duplicate applicant_id within the tenant (step 1) and analyzing an applicant with no documents
(step 3) return 409.
Async batch variant: POST /v1/batch/analyze with {"applicant_ids": ["CASE-...", "CASE-..."]}
runs asynchronously when the list reaches the tenant's async-batch threshold (default 50). It
returns 202 with a job_id; poll GET /v1/batch/jobs/{job_id}.
3. ZIP upload, submit and poll
A done job carries the ForensicResult in result. A failed job carries an error. Polling is a separate HTTP request, not an open connection waiting for completion.
Submit one .zip holding the full case package. Aletheia unpacks it, infers the document type per
entry from its filename (same table as path 1), and analyzes asynchronously: a case can take about
a minute per document, too long to hold one request open.
Submit, POST /analyze/zip. Multipart:
| Field | Required | Description |
|---|---|---|
file | yes | One .zip case package. Note: file, singular, unlike files on /analyze. |
applicant_id | no | Caller-supplied label |
case_meta | no | JSON string of arbitrary metadata |
metadata | no | Post-OCR metadata as JSON, see below |
case_type, manifest, master_data | no | Typed case types only; a manifest.json or the folder convention inside the ZIP also work, see Case types |
curl -sS -X POST "$ALETHEIA_BASE_URL/analyze/zip" \
-H "Authorization: Bearer $TOKEN" \
-F "file=@case.zip" \
-F "applicant_id=APP-12345"Returns 202 Accepted:
{ "job_id": "f1e2...", "status": "analyzing", "status_url": "/analyze/zip/f1e2..." }Poll, GET /analyze/zip/{job_id}. While running: {"job_id": "...", "status": "analyzing"}.
When complete, status is done and result carries the full ForensicResult (same shape as
path 1). A failed analysis returns status: "failed" with an error string. An unknown
job_id, or one belonging to another tenant, returns 404.
Archive rules. Entries must be .pdf/.jpg/.jpeg/.png/.heic/.heif/.tif/.tiff; document type is
inferred from each filename stem for the default case type, from a manifest for other case types.
Limits are 15
entries, 20 MB per entry, 50 MB total unpacked, 50 MB zip body. Encrypted, empty, nested-zip,
path-traversal, and zip-bomb archives are rejected with 422/413.
Post-OCR metadata (optional). If you already run your own OCR and hold a third-party audit
trail for it, send it alongside the ZIP as the multipart metadata part or as a metadata.json
entry inside the archive. It is stored and echoed back under intake_metadata in the poll
response; the engine still drives the verdict from Aletheia's own extraction.
4. Outbound result webhook
Requires a callback URL and HMAC secret provisioned for the tenant. Verify the raw body and handle event_id deduplication before acting on the result. Non-2xx delivery responses trigger the documented retry policy.
Aletheia POSTs the verdict to a callback URL you register; use this when you'd rather receive
the result than poll for it. Configured per tenant with a callback URL and a shared HMAC secret;
signed with X-Forensic-Signature (see Webhooks).
Retries: 3 attempts with exponential backoff on any non-2xx response; acknowledge with any 2xx.
The body is an AnalysisCompletedEvent:
| Field | Description |
|---|---|
event_type | always analysis_completed |
event_id | unique per delivery attempt chain; use it to deduplicate |
external_applicant_id | your applicant reference, echoed |
internal_applicant_id | Aletheia's applicant id |
verdict | REJECT, ESCALATE, PENDING, CONDITIONAL or PASS |
score | advisory score (integer) |
top_findings | up to 3 findings, most severe first: code, severity (lowercase), summary |
audit_reference | reference for the audit trail |
analyzed_at, event_timestamp | timestamps |
Persistent failures after the retries are queued internally and IDCanopy operations are alerted. The signed body is replayed unchanged on every attempt.
5. Inbound URL-fetch, optional
Optional, not recommended for new integrations. In this mode you host documents at HTTPS URLs
and Aletheia fetches them server-side, with an SSRF host-allowlist, HMAC request signing, and
idempotency. The endpoint is POST /v1/integrations/inbound/webhook; the tenant is derived from
the bearer key, and enrolment requires a provisioned inbound webhook secret, signed with the
X-Inbound-Signature header, see Webhooks. The
document host allowlist is registered per tenant during onboarding.
Which path to use
| If you are… | Use |
|---|---|
| just integrating and want the simplest path | (1) stateless /analyze |
| uploading documents incrementally or running async batches | (2) stateful v1 |
| handing off one signed bundle per case | (3) ZIP upload |
| an async result consumer that prefers callbacks over polling | (4) outbound webhook |
| an AI agent integrator | the MCP server wraps path 1 |
| a pipeline that already serves documents from HTTPS URLs | (5) inbound URL-fetch (optional) |