IDCanopy Developers

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 it

2. 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.verdict drives the decision: REJECT, ESCALATE, PENDING, CONDITIONAL or PASS, in that order of severity. Every verdict traces to the rules in override_rules_fired and reason_codes.
  • findings[] are the evidence. check_id values are stable and listed in check-catalog.json; message is the operator text from the message catalogue.
  • advisory_score (0 to 100) and advisory_band are 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.

On this page