IDCanopy Developers

Agents

Integrating an AI agent directly against the Aletheia API, the error model, limits and idempotency

This page describes stable protocol behaviour for an AI agent integrating programmatically against Aletheia, without the MCP server (see MCP server if you want typed tool calls instead). Terse and schema-cited. The authoritative machine-readable contract is the OpenAPI document, rendered in the reference; request/response schemas, security schemes, and error bodies are defined there. Implementation details of the server are deliberately omitted.

Authentication

There are two auth modes; which one applies is a server-side deployment setting. Production multi-tenant deployments use Mode A; Mode B exists for local and staging tooling.

Mode A, production multi-tenant

  • Tenant API key as bearer token: Authorization: Bearer fsk_<8-char-prefix>_<secret>.
  • Optional mTLS: where a tenant opts into connection-level client-certificate auth, the reverse proxy sets X-Client-Cert-Verify: SUCCESS and X-Client-Cert-DN: CN=<tenant-cn>,... on every inbound request. You never set these yourself. Not required by default, see mTLS.

The tenant identity is derived from the key, not from a header. X-Tenant-ID is ignored in this mode. Keys are issued by IDCanopy (no self-service).

On failure the middleware returns 401 with {"detail": "authentication required"} and no enumeration of which check failed.

Mode B, local and staging single-tenant

Authorization: Bearer <shared-service-token>
X-Tenant-ID: <tenant-slug>   # honoured only in this mode

The shared service token (32 characters or more) is provided to you by IDCanopy for the relevant environment. Never commit or log it. This mode is for local and staging tooling, not production traffic.

Pending verification: the Aletheia team's guide says "staging" here; the sandbox page says a sandbox tenant receives a fsk_ tenant key (Mode A) and that non-production hosts carry a -sbx, -test or -dev suffix. Which mode a sandbox tenant runs in is being confirmed.

Ingestion paths

See Submitting a case for the complete overview (stateless, stateful, ZIP, outbound webhook). The notes here focus on what an AI-agent integrator needs.

Path 1, stateless POST /analyze

  • Returns a synchronous ForensicResult (HTTP 200).
  • Side effects: none. No applicant state is persisted, no outbound webhook fires.
  • Use when: one-off checks, smoke tests, integrations that manage their own state.

Request: multipart/form-data

FieldTypeRequired
filesrepeated fileyes, 1 to 15 files
applicant_idstringno, caller-supplied label, not persisted
case_metaJSON stringno
case_type, manifest, master_datastring, JSON string, JSON stringno, see Case types
curl -X POST "$ALETHEIA_BASE_URL/analyze" \
  -H "Authorization: Bearer $FORENSIC_API_TOKEN" \
  -F "files=@/tmp/payslip.pdf" \
  -F "files=@/tmp/statement.pdf" \
  -F 'applicant_id=test-001'
import httpx, pathlib

def analyze(token: str, doc_paths: list[str], base_url: str = "https://aletheia.api-umbrella.io") -> dict:
    files = [("files", (pathlib.Path(p).name, open(p, "rb"))) for p in doc_paths]
    r = httpx.post(
        f"{base_url}/analyze",
        headers={"Authorization": f"Bearer {token}"},
        files=files,
        timeout=120,
    )
    r.raise_for_status()
    return r.json()

Path 2, stateful v1 lifecycle

Three sequential calls; applicant row and documents are persisted.

POST /v1/applicants                          -> 201 CreateApplicantResponse
POST /v1/applicants/{id}/documents           -> 201 UploadDocumentResponse
POST /v1/applicants/{id}/analyze             -> 200 ForensicResult
GET  /v1/applicants/{id}/findings            -> 200 (read after analyze)

Duplicate applicant_id (same tenant): POST /v1/applicants returns 409. Callers must supply a stable applicant_id and handle 409 as "already exists".

No documents uploaded: POST /v1/applicants/{id}/analyze returns 409.

The outbound result webhook fires for any tenant that has a callback URL and an outbound HMAC secret provisioned. Where the request originated from the inbound URL-fetch webhook, the outbound payload also echoes that submission's external_applicant_id.

# 1. create
APP=$(curl -sX POST "$ALETHEIA_BASE_URL/v1/applicants" \
  -H "Authorization: Bearer $FORENSIC_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"applicant_id":"app-001"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['applicant_id'])")

# 2. upload (multipart, repeated 'files' field)
curl -X POST "$ALETHEIA_BASE_URL/v1/applicants/$APP/documents" \
  -H "Authorization: Bearer $FORENSIC_API_TOKEN" \
  -F "files=@/tmp/payslip.pdf"

# 3. analyze
curl -X POST "$ALETHEIA_BASE_URL/v1/applicants/$APP/analyze" \
  -H "Authorization: Bearer $FORENSIC_API_TOKEN"

Inbound push webhook

For partners who push applicants to Aletheia rather than calling the paths above, there is a URL-fetch inbound webhook at POST /v1/integrations/inbound/webhook (the tenant is derived from the bearer key; enrolment requires a provisioned inbound webhook secret). Generic AI-agent integrators do not call this directly; they go through paths 1 or 2. See Submitting a case.

ForensicResult schema

Defined in the OpenAPI document as #/components/schemas/ForensicResult.

{
  "applicant_id": "app-001",
  "case_type": "account_application",
  "verdict": {
    "verdict": "REJECT",              // REJECT | ESCALATE | PENDING | CONDITIONAL | PASS
    "reason_codes": ["MRZ_CHECKSUM_FAIL"],
    "override_rules_fired": ["I1"],
    "verdict_explanation": ""
  },
  "findings": [
    {
      "check_id": "mrz_checksum_failure",
      "check_category": "identity",
      "severity": "HIGH",
      "summary": "MRZ check digit mismatch on birth date",
      "evidence_quote": "expected=3, computed=7",
      "source_document_id": "doc-uuid",
      "message": { "what": "...", "what_to_do": "..." },
      "metadata": {}
    }
  ],
  "advisory_score": 12,               // 0-100, informational only, does not drive verdict
  "advisory_band": "HIGH_RISK",       // HIGH_RISK | REVIEW | LOW_RISK
  "checker_version": "0.5.1-phase4",
  "analysis_ts": "2026-05-31T10:00:00Z",
  "recommended_action": "Request current payslip",
  "verdict_message": { "what": "...", "what_to_do": "..." },
  "tenant_config_hash": "sha256:..."  // null when no tenant configuration applies
}

Verdict order (severity): REJECT > ESCALATE > PENDING > CONDITIONAL > PASS.

Stable check_id, reason_code and override_rules_fired values are catalogued in check-catalog.json; tolerate unknown codes (forward-compatible). message and verdict_message carry the operator texts from the message catalogue. Typed case types add code, item_id and references per finding and risk_indicator, consistency_result, items and missing on the result, see Case types.

Error model

Extraction failures resolve to PENDING

Two distinct failure points both resolve to verdict = "PENDING":

Finding check_idOriginRuleMeaning
extraction_failedCheck-level extraction call failureQ3A single document-extraction call failed (HTTP 4xx/5xx, timeout, parse error). Evidence is incomplete; verdict deferred.
Q3_EXTRACTION_FAILURECase-level extraction abort(finding itself)The entire extraction stage failed. All evidence is unavailable; verdict deferred.

Both yield ForensicResult.verdict.verdict = "PENDING", but they surface differently:

  • Check-level extraction_failed fires override rule Q3, so verdict.override_rules_fired contains "Q3".
  • Case-level Q3_EXTRACTION_FAILURE builds a direct PENDING verdict with verdict.override_rules_fired = [] and verdict.reason_codes = ["Q3_EXTRACTION_FAILURE"] (no override rule fires).

Retry: resubmit when the extraction provider is healthy. No verdict is produced until extraction succeeds.

MRZ composite corroboration

When a composite MRZ checksum field (a check digit that covers multiple fields) mismatches:

forensic_id stateSeverity emittedVerdict floor
forensic_id_authenticINFOnone
forensic_id_flaggedHIGHreview floor (ESCALATE)
forensic_id_unavailableHIGHreview floor (ESCALATE)

mrz_checksum_failure is not emitted for composite-only mismatches. The outcome is review-flagged at most; it is not an automatic REJECT.

HTTP error codes

Error bodies are ProblemDetails: {"detail": "..."}, plus trace_id on 5xx from the stateless /analyze endpoints. 429 uses RateLimitError instead, see below.

CodeMeaning
400No files submitted; or a batch below the async threshold on POST /v1/batch/analyze
401Auth failed
404Unknown applicant or job, or one belonging to another tenant
409Duplicate applicant_id (v1) or no documents uploaded before analyze (v1)
413Too many files, file too large, or body too large
422Unsupported file extension, malformed JSON, invalid case-type fields, or tenant not configured (for example no inbound webhook secret)
429Rate limit exceeded, see the Retry-After header
502Document URL fetch failed (inbound webhook)
500Internal error. trace_id in the body only on stateless /analyze; v1 endpoints return plain {"detail": "..."} without a trace id

Limits

File upload

LimitValue
Max files per request15
Max size per file20 MB
Max total body50 MB
Accepted extensions.pdf .jpg .jpeg .heic .heif .png .tif .tiff

Upload field name is files (repeated). Example with two files:

multipart/form-data:
  files: <bytes of payslip.pdf>
  files: <bytes of statement.pdf>

Rate limiting

Active in production.

  • 60 requests per minute per tenant (default; overridable via tenant configuration).
  • Breach: HTTP 429 with a Retry-After: <seconds-to-next-window> header and the body {"error": "rate_limit_exceeded", "retry_after": N} (the RateLimitError schema).
  • /v1/batch/* is exempt from per-request rate limiting, as are /healthz, /metrics, /docs and /v1/billing/*.

Idempotency

Applies to POST /v1/integrations/inbound/webhook only.

  • Header: X-Idempotency-Key: <caller-supplied UUID>.
  • Replay window: 24 hours. A second call with the same key within 24 h returns the cached 202 response with "idempotency_replay": true. The key is optional; if omitted, the request is treated as fresh and no de-duplication occurs.

For the v1 stateful path, idempotency is the caller's responsibility:

  • Supply a stable, unique applicant_id at creation time.
  • POST /v1/applicants with a duplicate id returns 409; handle it as "already registered".

Pagination and polling, explicit non-goals

  • No applicant-list endpoint. There is no paginated GET /v1/applicants.
  • POST /analyze and POST /v1/applicants/{id}/analyze are synchronous. No polling needed; the response is the result.
  • After POST /v1/applicants/{id}/analyze, use GET /v1/applicants/{id}/findings to retrieve stored findings for that applicant.
  • Polling applies only to ZIP jobs (GET /analyze/zip/{job_id}), /v1/batch/* async jobs and inbound-webhook portfolio sweep jobs (GET /v1/batch/jobs/{job_id}). All other paths return results directly.

On this page