IDCanopy Developers

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.

PathDirectionSync?Use when
(a) Stateless POST /analyzeclient to us, pushsyncone-shot integrations, demos
(b) Stateful v1 lifecycleclient to us, pushasync-capableuploads over time, separated audit, async batch
(c) ZIP uploadclient to us, pushasync (submit + poll)one signed bundle per case
(d) Outbound result webhookus to client, pushn/aregister 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 as grant_settlement (an application plus cost items made of invoice, payment proof and proof of service), send the optional case_type, manifest and master_data fields 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.

One synchronous analysis request
One synchronous analysis requestYour backend to Aletheia: POST /analyze with the case files. Aletheia to Your backend: 200: ForensicResultYour backendAletheia1. POST /analyze with the case files2. 200: ForensicResult

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:

FieldRequiredDescription
filesyes1-15 files, repeat the field name per file. PDF, JPG, PNG, HEIC, TIFF. Max 20 MB each, 50 MB total.
applicant_idnoCaller-supplied label, echoed in the response
case_metanoJSON string of arbitrary metadata, logged in the audit trail
case_type, manifest, master_datanoTyped 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 detectedFilename contains
identitypassport, reisepass, ausweis, id, identity, rp, bg, fs, pa, personalausweis, führerschein, fuhrerschein
payslippayslip, gehaltszettel, gz, lohnzettel, salary
bank_statementbank, kaz, kontoauszug, statement, konto
pensionsbescheidpensionsbescheid, 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 500 on /analyze, the Aletheia team's guide says detail can be an object carrying trace_id and error_code, and that /analyze/report carries a trace_id too; the specification's ProblemDetails has detail as a string with trace_id as a sibling field, present on /analyze 5xx 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.

Upload over time, then analyse
Upload over time, then analyseYour backend to Aletheia: POST /v1/applicants. Aletheia to Your backend: 201: applicant created. Your backend to Aletheia: POST /v1/applicants/{id}/documents (repeat as needed). Aletheia to Your backend: 201: documents stored. Your backend to Aletheia: POST /v1/applicants/{id}/analyze. Aletheia to Your backend: 200: ForensicResult. Your backend to Aletheia: GET /v1/applicants/{id}/findings (optional, later). Aletheia to Your backend: Stored findingsYour backendAletheia1. POST /v1/applicants2. 201: applicant created3. POST /v1/applicants/{id}/documents (repeat as needed)4. 201: documents stored5. POST /v1/applicants/{id}/analyze6. 200: ForensicResult7. GET /v1/applicants/{id}/findings (optional, later)8. Stored findings

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

Submit a ZIP and poll its job
Submit a ZIP and poll its jobYour backend to Aletheia: POST /analyze/zip with the ZIP file. Aletheia to Your backend: 202: job_id and status_url. Your backend to Aletheia: GET /analyze/zip/{job_id} (repeat while analyzing). Aletheia to Your backend: Job status: analyzing, done or failedYour backendAletheia1. POST /analyze/zip with the ZIP file2. 202: job_id and status_url3. GET /analyze/zip/{job_id} (repeat while analyzing)4. Job status: analyzing, done or failed

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:

FieldRequiredDescription
fileyesOne .zip case package. Note: file, singular, unlike files on /analyze.
applicant_idnoCaller-supplied label
case_metanoJSON string of arbitrary metadata
metadatanoPost-OCR metadata as JSON, see below
case_type, manifest, master_datanoTyped 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

Receive a signed result callback
Receive a signed result callbackAletheia to Your webhook endpoint: POST AnalysisCompletedEvent + X-Forensic-Signature. Your webhook endpoint to Aletheia: 2xx acknowledgement after signature verificationAletheiaYour webhook endpoint1. POST AnalysisCompletedEvent + X-Forensic-Signature2. 2xx acknowledgement after signature verification

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:

FieldDescription
event_typealways analysis_completed
event_idunique per delivery attempt chain; use it to deduplicate
external_applicant_idyour applicant reference, echoed
internal_applicant_idAletheia's applicant id
verdictREJECT, ESCALATE, PENDING, CONDITIONAL or PASS
scoreadvisory score (integer)
top_findingsup to 3 findings, most severe first: code, severity (lowercase), summary
audit_referencereference for the audit trail
analyzed_at, event_timestamptimestamps

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 integratorthe MCP server wraps path 1
a pipeline that already serves documents from HTTPS URLs(5) inbound URL-fetch (optional)

On this page