{
  "openapi": "3.1.0",
  "info": {
    "title": "IDCanopy Aletheia",
    "description": "Aletheia receives document packages, runs deterministic fraud and forgery checks, and returns a verdict (`REJECT`, `ESCALATE`, `PENDING`, `CONDITIONAL` or `PASS`) with auditable, named-rule evidence.\n\nTwo integration flows: the stateful **v1 lifecycle** (`POST /v1/applicants`, then `.../documents`, `.../analyze`, `GET .../findings`) and the **inbound webhook** (`POST /v1/integrations/inbound/webhook`), HMAC-signed and idempotent. `POST /analyze` and `POST /analyze/zip` analyse a case in one call.\n\nVerdicts are deterministic: the same evidence yields the same verdict, and every verdict traces to a named rule. Only the vision-language extraction stage is non-deterministic.\n\n**Auth.** Bearer API key on every request (`Authorization: Bearer fsk_...`); the tenant is derived from the key. mTLS is optional connection hardening, see [mTLS](/services/forensic-scoring-api/mtls/).\n\n**For AI agents:** the MCP server `idcanopy-aletheia-mcp` (PyPI), see [MCP](/services/forensic-scoring-api/mcp/) and [Agents](/services/forensic-scoring-api/agents/).",
    "version": "0.5.1-phase4"
  },
  "paths": {
    "/healthz": {
      "get": {
        "tags": [
          "meta"
        ],
        "summary": "Healthz",
        "description": "Health check, returns immediately, no downstream I/O.",
        "operationId": "healthz_healthz_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object",
                  "title": "Response Healthz Healthz Get"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/version": {
      "get": {
        "tags": [
          "meta"
        ],
        "summary": "Version",
        "description": "Version + build metadata.",
        "operationId": "version_version_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object",
                  "title": "Response Version Version Get"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/analyze": {
      "post": {
        "tags": [
          "analyze"
        ],
        "summary": "Analyze",
        "description": "Forensic analysis of a set of PDF/JPG documents for a single applicant.\nReturns ForensicResult JSON.",
        "operationId": "analyze_analyze_post",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_analyze_analyze_post"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForensicResult"
                }
              }
            }
          },
          "400": {
            "description": "No document file uploaded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed (missing/invalid bearer token).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "413": {
            "description": "Request body, file count or file size over the limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the next window.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/analyze/report": {
      "post": {
        "tags": [
          "analyze"
        ],
        "summary": "Analyze Report",
        "description": "Forensic analysis + PDF report generation.\nReturns application/pdf with Content-Disposition: attachment.",
        "operationId": "analyze_report_analyze_report_post",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_analyze_report_analyze_report_post"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "PDF forensic report; Content-Disposition: attachment",
            "content": {
              "application/pdf": {}
            }
          },
          "400": {
            "description": "No document file uploaded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed (missing/invalid bearer token).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "413": {
            "description": "Request body, file count or file size over the limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the next window.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/analyze/zip": {
      "post": {
        "tags": [
          "analyze"
        ],
        "summary": "Submit Analyze Zip",
        "description": "Submit a ZIP case package for async analysis. Returns 202 + a poll URL.",
        "operationId": "submit_analyze_zip_analyze_zip_post",
        "parameters": [
          {
            "name": "x-tenant-id",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Tenant-Id"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_submit_analyze_zip_analyze_zip_post"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ZipSubmitResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed (missing/invalid bearer token).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "413": {
            "description": "ZIP body / entry / unpacked-size limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the next window.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/analyze/zip/{job_id}": {
      "get": {
        "tags": [
          "analyze"
        ],
        "summary": "Get Analyze Zip",
        "description": "Poll a ZIP analysis job. Tenant-isolated: other tenants receive 404.",
        "operationId": "get_analyze_zip_analyze_zip__job_id__get",
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Job Id"
            }
          },
          {
            "name": "x-tenant-id",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Tenant-Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ZipJobResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed (missing/invalid bearer token).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Job not found (or owned by another tenant).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the next window.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/v1/applicants": {
      "post": {
        "tags": [
          "v1"
        ],
        "summary": "Create Applicant",
        "description": "Create a new applicant row. Returns 409 if applicant_id already exists for tenant.",
        "operationId": "create_applicant_v1_applicants_post",
        "parameters": [
          {
            "name": "x-tenant-id",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Tenant-Id"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateApplicantRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateApplicantResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed (missing/invalid bearer token).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "An applicant with this external id already exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the next window.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/v1/applicants/{applicant_id}/manifest": {
      "put": {
        "tags": [
          "v1"
        ],
        "summary": "Put Manifest",
        "description": "Set or replace the manifest (files → roles / items) before analyze.\n\n422 if the applicant's case type takes no manifest (account_application) or the\nmanifest uses roles the type does not declare.",
        "operationId": "put_manifest_v1_applicants__applicant_id__manifest_put",
        "parameters": [
          {
            "name": "applicant_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Applicant Id"
            }
          },
          {
            "name": "x-tenant-id",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Tenant-Id"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CaseManifest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ManifestResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed (missing/invalid bearer token).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the next window.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/v1/applicants/{applicant_id}/documents": {
      "post": {
        "tags": [
          "v1"
        ],
        "summary": "Upload Documents",
        "description": "Upload documents for an applicant. Files are stored on disk; metadata in DB.",
        "operationId": "upload_documents_v1_applicants__applicant_id__documents_post",
        "parameters": [
          {
            "name": "applicant_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Applicant Id"
            }
          },
          {
            "name": "x-tenant-id",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Tenant-Id"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_upload_documents_v1_applicants__applicant_id__documents_post"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadDocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed (missing/invalid bearer token).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Applicant not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the next window.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/v1/applicants/{applicant_id}/analyze": {
      "post": {
        "tags": [
          "v1"
        ],
        "summary": "Analyze Applicant",
        "description": "Load stored docs, run the engine, persist results. 409 if no documents.",
        "operationId": "analyze_applicant_v1_applicants__applicant_id__analyze_post",
        "parameters": [
          {
            "name": "applicant_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Applicant Id"
            }
          },
          {
            "name": "x-tenant-id",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Tenant-Id"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnalyzeRequest",
                "default": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForensicResult"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed (missing/invalid bearer token).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Applicant not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "No documents uploaded for this applicant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the next window.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/v1/batch/cross-check": {
      "post": {
        "tags": [
          "v1"
        ],
        "summary": "Batch Cross Check",
        "description": "Run cross-applicant checks across pre-analyzed applicants.\n\nBuilds ApplicantCaseData from persisted ForensicResults + historical signals\n(employer fingerprint loaded from signals DB when available) and calls\nrun_checks(skip_biometric=True). Cross-batch repeat-fraud signals fire when\nthe tenant has signals_db enabled and the applicant's signals were seeded.\n\n422 if any applicant_id has no findings yet.",
        "operationId": "batch_cross_check_v1_batch_cross_check_post",
        "parameters": [
          {
            "name": "x-tenant-id",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Tenant-Id"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchCrossCheckRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchCrossCheckResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed (missing/invalid bearer token).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/v1/applicants/{applicant_id}/findings": {
      "get": {
        "tags": [
          "v1"
        ],
        "summary": "Get Findings",
        "description": "Return the persisted ForensicResult. 404 if no analyze has run yet.",
        "operationId": "get_findings_v1_applicants__applicant_id__findings_get",
        "parameters": [
          {
            "name": "applicant_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Applicant Id"
            }
          },
          {
            "name": "x-tenant-id",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Tenant-Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForensicResult"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed (missing/invalid bearer token).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Applicant or findings not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the next window.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/v1/applicants/{applicant_id}/report": {
      "post": {
        "tags": [
          "v1"
        ],
        "summary": "Get Report",
        "description": "Generate and return a PDF forensic report for an applicant.\n409 if no analyze has run yet.",
        "operationId": "get_report_v1_applicants__applicant_id__report_post",
        "parameters": [
          {
            "name": "applicant_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Applicant Id"
            }
          },
          {
            "name": "x-tenant-id",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Tenant-Id"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReportRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "PDF forensic report; Content-Disposition: attachment",
            "content": {
              "application/pdf": {}
            }
          },
          "401": {
            "description": "Authentication failed (missing/invalid bearer token).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Applicant not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "Applicant has not been analyzed yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the next window.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/v1/batch/analyze": {
      "post": {
        "tags": [
          "batch"
        ],
        "summary": "Submit Batch Analyze",
        "description": "Submit an async batch analysis job.\n\nReturns 400 if len(applicant_ids) < tenant's async_batch_threshold.\nReturns 429 if the per-tenant concurrent batch cap is reached.\nReturns 202 with job_id + status_url within < 500 ms.",
        "operationId": "submit_batch_analyze_v1_batch_analyze_post",
        "parameters": [
          {
            "name": "x-tenant-id",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Tenant-Id"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchAnalyzeRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "title": "Response Submit Batch Analyze V1 Batch Analyze Post"
                }
              }
            }
          },
          "400": {
            "description": "Fewer applicant ids than the batch threshold; use the single-applicant analyze.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed (missing/invalid bearer token).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "429": {
            "description": "Per-tenant concurrent batch cap reached."
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/v1/batch/jobs/{job_id}": {
      "get": {
        "tags": [
          "batch"
        ],
        "summary": "Get Batch Job",
        "description": "Return job status. Tenant-isolated: other tenants receive 404.",
        "operationId": "get_batch_job_v1_batch_jobs__job_id__get",
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Job Id"
            }
          },
          {
            "name": "x-tenant-id",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Tenant-Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchJobStatus"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed (missing/invalid bearer token).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Job not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/v1/integrations/inbound/webhook": {
      "post": {
        "tags": [
          "integrations"
        ],
        "summary": "Inbound Webhook",
        "description": "Inbound webhook called by a tenant's onboarding platform when an applicant submits documents. Accepts two event types: `applicant_submitted` (single applicant, runs analysis immediately and fires the outbound webhook when done) and `portfolio_sweep` (multiple applicants, enqueues an async batch job).\n\n**Security:** requires `Authorization: Bearer <tenant-api-key>` (the tenant identity is derived from the key) plus an `X-Inbound-Signature: HMAC-SHA256(raw_body, inbound_webhook_secret)` header (constant-time comparison). Body capped at 50 MB. SSRF protection: document URLs must be HTTPS and match the `inbound_doc_url_allowlist` configured for the tenant, hard-fail closed if not configured. Tenants without an `inbound_webhook_secret` provisioned are not enrolled for this surface (422).\n\n**Idempotency:** duplicate `X-Idempotency-Key` within 24 h returns 202 with the original `internal_applicant_id` and `idempotency_replay: true`.",
        "operationId": "inbound_webhook_v1_integrations_inbound_webhook_post",
        "parameters": [
          {
            "name": "x-tenant-id",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Tenant-Id"
            }
          },
          {
            "name": "X-Inbound-Signature",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Inbound-Signature"
            }
          },
          {
            "name": "X-Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Idempotency-Key"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InboundWebhookAccepted"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid `Authorization` bearer token, or HMAC-SHA256 signature mismatch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "413": {
            "description": "Request body exceeds 50 MB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "422": {
            "description": "Unrecognised `event_type`, missing required fields, or tenant not configured (missing `inbound_webhook_secret` or `inbound_doc_url_allowlist`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the next window.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "502": {
            "description": "Document fetch from a document URL failed (URL unreachable, size limit exceeded, or sha256 mismatch)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "title": "applicant_submitted",
                    "description": "Single applicant submitted for onboarding.",
                    "type": "object",
                    "required": [
                      "event_type",
                      "external_applicant_id",
                      "documents"
                    ],
                    "properties": {
                      "event_type": {
                        "type": "string",
                        "enum": [
                          "applicant_submitted"
                        ]
                      },
                      "external_applicant_id": {
                        "type": "string",
                        "example": "APP-2026-000123"
                      },
                      "submitted_at": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "applicant": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "iban": {
                            "type": "string",
                            "example": "AT611904300234573201"
                          },
                          "dob": {
                            "type": "string",
                            "format": "date"
                          }
                        }
                      },
                      "documents": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "required": [
                            "url"
                          ],
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": [
                                "id_front",
                                "id_back",
                                "payslip",
                                "bank_statement",
                                "pensionsbescheid"
                              ]
                            },
                            "url": {
                              "type": "string",
                              "format": "uri"
                            },
                            "sha256": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  },
                  {
                    "title": "portfolio_sweep",
                    "description": "Batch of applicants for portfolio sweep, enqueues an async batch job.",
                    "type": "object",
                    "required": [
                      "event_type",
                      "applicants"
                    ],
                    "properties": {
                      "event_type": {
                        "type": "string",
                        "enum": [
                          "portfolio_sweep"
                        ]
                      },
                      "applicants": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "required": [
                            "external_applicant_id"
                          ],
                          "properties": {
                            "external_applicant_id": {
                              "type": "string"
                            },
                            "submitted_at": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "applicant": {
                              "type": "object"
                            },
                            "documents": {
                              "type": "array",
                              "items": {
                                "type": "object"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                ]
              },
              "examples": {
                "applicant_submitted": {
                  "summary": "Single applicant submission",
                  "value": {
                    "event_type": "applicant_submitted",
                    "external_applicant_id": "APP-2026-000123",
                    "submitted_at": "2026-09-15T08:30:00Z",
                    "applicant": {
                      "name": "Max Mustermann",
                      "iban": "AT611904300234573201",
                      "dob": "1985-03-12"
                    },
                    "documents": [
                      {
                        "type": "id_front",
                        "url": "https://docs.example/doc1",
                        "sha256": "aabbcc..."
                      },
                      {
                        "type": "payslip",
                        "url": "https://docs.example/doc2",
                        "sha256": "ddeeff..."
                      },
                      {
                        "type": "bank_statement",
                        "url": "https://docs.example/doc3",
                        "sha256": "112233..."
                      }
                    ]
                  }
                },
                "portfolio_sweep": {
                  "summary": "Portfolio sweep (multiple applicants)",
                  "value": {
                    "event_type": "portfolio_sweep",
                    "applicants": [
                      {
                        "external_applicant_id": "APP-2026-000123",
                        "submitted_at": "2026-09-15T08:30:00Z",
                        "applicant": {
                          "name": "Max Mustermann"
                        },
                        "documents": [
                          {
                            "type": "id_front",
                            "url": "https://docs.example/doc1"
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "callbacks": {
          "analysisCompleted": {
            "{$tenant.webhooks.endpoint}": {
              "post": {
                "summary": "Outbound webhook (analysis_completed)",
                "description": "Fired once per applicant when analysis completes, to the callback URL configured in the tenant's webhook settings (not supplied in the request). Delivered up to 3 times with exponential backoff (1s, 2s, 4s) on a non-2xx or connection error; the receiver must respond 2xx to acknowledge. The body is signed; verify `X-Forensic-Signature` before trusting it.",
                "parameters": [
                  {
                    "name": "X-Forensic-Signature",
                    "in": "header",
                    "required": true,
                    "schema": {
                      "type": "string"
                    },
                    "description": "Lowercase hex HMAC-SHA256 of the exact raw request body, keyed with the shared webhook secret."
                  }
                ],
                "requestBody": {
                  "required": true,
                  "content": {
                    "application/json": {
                      "schema": {
                        "$ref": "#/components/schemas/AnalysisCompletedEvent"
                      }
                    }
                  }
                },
                "responses": {
                  "2XX": {
                    "description": "Acknowledged. Any 2xx stops retries."
                  },
                  "4XX": {
                    "description": "Permanent failure, IDCanopy does NOT retry."
                  },
                  "5XX": {
                    "description": "Transient failure, IDCanopy retries with backoff, then DLQs."
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AdvisoryBand": {
        "type": "string",
        "enum": [
          "HIGH_RISK",
          "REVIEW",
          "LOW_RISK"
        ],
        "title": "AdvisoryBand",
        "description": "Advisory score band, informational only, does NOT drive verdict."
      },
      "AnalyzeRequest": {
        "properties": {
          "case_meta_override": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Case Meta Override"
          }
        },
        "type": "object",
        "title": "AnalyzeRequest"
      },
      "BatchAnalyzeRequest": {
        "properties": {
          "applicant_ids": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "minItems": 1,
            "title": "Applicant Ids"
          }
        },
        "type": "object",
        "required": [
          "applicant_ids"
        ],
        "title": "BatchAnalyzeRequest"
      },
      "BatchCrossCheckRequest": {
        "properties": {
          "applicant_ids": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Applicant Ids"
          },
          "tenant_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Tenant Id"
          }
        },
        "type": "object",
        "required": [
          "applicant_ids"
        ],
        "title": "BatchCrossCheckRequest"
      },
      "BatchCrossCheckResponse": {
        "properties": {
          "findings": {
            "items": {
              "$ref": "#/components/schemas/Finding"
            },
            "type": "array",
            "title": "Findings"
          },
          "applicant_count": {
            "type": "integer",
            "title": "Applicant Count"
          },
          "ring_findings": {
            "items": {
              "$ref": "#/components/schemas/Finding"
            },
            "type": "array",
            "title": "Ring Findings"
          }
        },
        "type": "object",
        "required": [
          "findings",
          "applicant_count",
          "ring_findings"
        ],
        "title": "BatchCrossCheckResponse"
      },
      "BatchJobStatus": {
        "properties": {
          "job_id": {
            "type": "string",
            "title": "Job Id"
          },
          "tenant_id": {
            "type": "string",
            "title": "Tenant Id"
          },
          "status": {
            "type": "string",
            "title": "Status"
          },
          "total": {
            "type": "integer",
            "title": "Total"
          },
          "completed": {
            "type": "integer",
            "title": "Completed"
          },
          "failed": {
            "type": "integer",
            "title": "Failed"
          },
          "webhook_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Webhook Url"
          },
          "created_at": {
            "title": "Created At"
          },
          "completed_at": {
            "title": "Completed At"
          }
        },
        "type": "object",
        "required": [
          "job_id",
          "tenant_id",
          "status",
          "total",
          "completed",
          "failed",
          "webhook_url",
          "created_at",
          "completed_at"
        ],
        "title": "BatchJobStatus"
      },
      "Body_analyze_analyze_post": {
        "properties": {
          "files": {
            "items": {
              "type": "string",
              "contentMediaType": "application/octet-stream"
            },
            "type": "array",
            "title": "Files",
            "description": "1–15 PDF or JPG files"
          },
          "applicant_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Applicant Id"
          },
          "case_meta": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Case Meta",
            "description": "Optional JSON string"
          },
          "case_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Case Type",
            "description": "Optional case type, e.g. 'grant_settlement'. Default: account_application."
          },
          "manifest": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Manifest",
            "description": "Optional JSON string: files → roles / items (typed case types only)."
          },
          "master_data": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Master Data",
            "description": "Optional JSON string: applicant master data (typed case types only)."
          }
        },
        "type": "object",
        "required": [
          "files"
        ],
        "title": "Body_analyze_analyze_post"
      },
      "Body_analyze_report_analyze_report_post": {
        "properties": {
          "files": {
            "items": {
              "type": "string",
              "contentMediaType": "application/octet-stream"
            },
            "type": "array",
            "title": "Files",
            "description": "1–15 PDF or JPG files"
          },
          "applicant_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Applicant Id"
          },
          "case_meta": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Case Meta",
            "description": "Optional JSON string"
          }
        },
        "type": "object",
        "required": [
          "files"
        ],
        "title": "Body_analyze_report_analyze_report_post"
      },
      "Body_submit_analyze_zip_analyze_zip_post": {
        "properties": {
          "file": {
            "type": "string",
            "contentMediaType": "application/octet-stream",
            "title": "File",
            "description": "A single .zip case package"
          },
          "applicant_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Applicant Id"
          },
          "case_meta": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Case Meta",
            "description": "Optional JSON string"
          },
          "metadata": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Metadata",
            "description": "Optional post-OCR metadata + e-signature audit trail (JSON)"
          },
          "case_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Case Type",
            "description": "Optional case type, e.g. 'grant_settlement'. Default: account_application."
          },
          "manifest": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Manifest",
            "description": "Optional JSON string: files → roles / items (typed case types only). Wins over a manifest.json at the ZIP root."
          },
          "master_data": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Master Data",
            "description": "Optional JSON string: applicant master data (typed case types only)."
          }
        },
        "type": "object",
        "required": [
          "file"
        ],
        "title": "Body_submit_analyze_zip_analyze_zip_post"
      },
      "Body_upload_documents_v1_applicants__applicant_id__documents_post": {
        "properties": {
          "files": {
            "items": {
              "type": "string",
              "contentMediaType": "application/octet-stream"
            },
            "type": "array",
            "title": "Files"
          }
        },
        "type": "object",
        "required": [
          "files"
        ],
        "title": "Body_upload_documents_v1_applicants__applicant_id__documents_post"
      },
      "CaseManifest": {
        "properties": {
          "application": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Application"
          },
          "membership_proof": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Membership Proof"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/ManifestItem"
            },
            "type": "array",
            "title": "Items"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "title": "CaseManifest",
        "description": "Assigns uploaded files (by filename) to case-level roles and to items."
      },
      "CheckOutcome": {
        "properties": {
          "check_id": {
            "type": "string",
            "title": "Check Id"
          },
          "name": {
            "type": "string",
            "title": "Name"
          },
          "category": {
            "type": "string",
            "title": "Category"
          },
          "description": {
            "type": "string",
            "title": "Description"
          },
          "status": {
            "type": "string",
            "title": "Status",
            "description": "PASS | ATTENTION | N/A"
          },
          "severity": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Severity",
            "description": "Highest finding severity when status == ATTENTION; else None."
          },
          "requires": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Requires",
            "description": "Doc types that must be present for the check to run."
          }
        },
        "type": "object",
        "required": [
          "check_id",
          "name",
          "category",
          "description",
          "status"
        ],
        "title": "CheckOutcome",
        "description": "One catalog check and the status it resolved to for this case."
      },
      "ChecksPerformed": {
        "properties": {
          "total": {
            "type": "integer",
            "title": "Total"
          },
          "passed": {
            "type": "integer",
            "title": "Passed"
          },
          "attention": {
            "type": "integer",
            "title": "Attention"
          },
          "not_applicable": {
            "type": "integer",
            "title": "Not Applicable"
          },
          "checks": {
            "items": {
              "$ref": "#/components/schemas/CheckOutcome"
            },
            "type": "array",
            "title": "Checks"
          }
        },
        "type": "object",
        "required": [
          "total",
          "passed",
          "attention",
          "not_applicable"
        ],
        "title": "ChecksPerformed",
        "description": "The complete set of checks evaluated, every catalog entry with its status.\n\nUnlike findings[] (which lists only checks that *fired*), this shows the full\nuniverse: what passed, what needs attention, and what was not applicable."
      },
      "CommercialSignal": {
        "properties": {
          "signal_id": {
            "type": "string",
            "title": "Signal Id",
            "description": "Stable identifier, e.g. 'exit_payslip_detected'."
          },
          "category": {
            "type": "string",
            "title": "Category",
            "description": "Signal category, e.g. 'employment_exit'."
          },
          "summary": {
            "type": "string",
            "title": "Summary",
            "description": "Human-readable summary for the bank relationship team."
          },
          "evidence_quote": {
            "type": "string",
            "title": "Evidence Quote",
            "description": "Specific evidence string.",
            "default": ""
          },
          "source_document_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Document Id"
          },
          "metadata": {
            "additionalProperties": true,
            "type": "object",
            "title": "Metadata"
          }
        },
        "type": "object",
        "required": [
          "signal_id",
          "category",
          "summary"
        ],
        "title": "CommercialSignal",
        "description": "A commercial / retention signal produced during forensic analysis.\n\nCommercial signals are informational outputs for the bank relationship team, NOT fraud findings. They must not influence the PolicyVerdict.\n\nExample: exit_payslip_detected, income is no longer current (employment ended),\nwhich is a retention / creditworthiness concern, not a fraud indicator."
      },
      "ConsistencyResult": {
        "type": "string",
        "enum": [
          "match",
          "mismatch",
          "not_checkable"
        ],
        "title": "ConsistencyResult",
        "description": "Roll-up of the consistency checks for an item or a case."
      },
      "CreateApplicantRequest": {
        "properties": {
          "applicant_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Applicant Id"
          },
          "case_meta": {
            "additionalProperties": true,
            "type": "object",
            "title": "Case Meta"
          },
          "case_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Case Type",
            "description": "Optional case type, e.g. 'grant_settlement'. Absent = account_application (today's behaviour). Unknown → 422; not held by the tenant → 403 case_type_not_allowed."
          },
          "manifest": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CaseManifest"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional files → roles / items assignment. Typed case types only; may also be set later with PUT /v1/applicants/{id}/manifest."
          },
          "master_data": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/GrantSettlementMasterData"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional applicant master data. Typed case types only; stored encrypted."
          }
        },
        "type": "object",
        "title": "CreateApplicantRequest"
      },
      "CreateApplicantResponse": {
        "properties": {
          "applicant_id": {
            "type": "string",
            "title": "Applicant Id"
          },
          "tenant_id": {
            "type": "string",
            "title": "Tenant Id"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
          },
          "case_type": {
            "type": "string",
            "title": "Case Type",
            "default": "account_application"
          }
        },
        "type": "object",
        "required": [
          "applicant_id",
          "tenant_id",
          "created_at"
        ],
        "title": "CreateApplicantResponse"
      },
      "DocumentSummary": {
        "properties": {
          "document_id": {
            "type": "string",
            "title": "Document Id"
          },
          "filename": {
            "type": "string",
            "title": "Filename"
          },
          "byte_size": {
            "type": "integer",
            "title": "Byte Size"
          },
          "content_sha256": {
            "type": "string",
            "title": "Content Sha256"
          }
        },
        "type": "object",
        "required": [
          "document_id",
          "filename",
          "byte_size",
          "content_sha256"
        ],
        "title": "DocumentSummary"
      },
      "ExtractedData": {
        "properties": {
          "identity": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Identity"
          },
          "payslips": {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "type": "array",
            "title": "Payslips"
          },
          "bank_statement": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Bank Statement"
          },
          "pensionsbescheide": {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "type": "array",
            "title": "Pensionsbescheide"
          }
        },
        "type": "object",
        "title": "ExtractedData",
        "description": "The facts the extraction layer read from each document.\n\nIBANs are truncated to the first 8 chars and SV numbers to the last 4,\nmirroring the PDF report's disclosure policy."
      },
      "Finding": {
        "properties": {
          "check_id": {
            "type": "string",
            "title": "Check Id",
            "description": "Stable check identifier, e.g. 'mrz_checksum_failure'."
          },
          "check_category": {
            "type": "string",
            "title": "Check Category",
            "description": "Category: 'metadata', 'identity', 'payslip', 'bank_statement', 'cross_document', 'cross_applicant', 'quality_gate'."
          },
          "severity": {
            "$ref": "#/components/schemas/FindingSeverity"
          },
          "summary": {
            "type": "string",
            "title": "Summary",
            "description": "Human-readable finding summary. DEPRECATED for operator display: kept as an alias of `message.what` for one minor version while clients migrate to `message`. Authored by the check module; not catalogued or localized."
          },
          "message": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Message"
              },
              {
                "type": "null"
              }
            ],
            "description": "Operator-facing message (what + what_to_do) resolved from the message catalog at response time. None only if resolution was not run (engine-internal use)."
          },
          "sku_attribution": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Sku Attribution",
            "description": "Commercial SKU code(s) that surface this check, e.g. ['A2']. Display metadata sourced from sku-attribution.json, NOT an access control."
          },
          "evidence_quote": {
            "type": "string",
            "title": "Evidence Quote",
            "description": "Specific evidence string (arithmetic, timestamp, field value, etc.).",
            "default": ""
          },
          "source_document_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Document Id"
          },
          "source_regions": {
            "additionalProperties": true,
            "type": "object",
            "title": "Source Regions",
            "description": "{page: int, bbox: [x1,y1,x2,y2]}."
          },
          "extraction_confidence": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Extraction Confidence",
            "description": "Confidence of the underlying extraction that produced this finding. A REJECT finding is suppressed if extraction_confidence < confidence_threshold in the matching override rule."
          },
          "internal": {
            "type": "boolean",
            "title": "Internal",
            "description": "When True, this finding is an internal signal for ring detection only. It must be filtered from customer-visible ForensicResult.findings.",
            "default": false
          },
          "metadata": {
            "additionalProperties": true,
            "type": "object",
            "title": "Metadata",
            "description": "Check-specific structured data (e.g. computed vs expected values)."
          },
          "code": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Code",
            "description": "External code from the case type's code map (e.g. 'UP-06a'). Null for account_application and for checks without a mapped code."
          },
          "item_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Item Id",
            "description": "Manifest item this finding belongs to. Null = case-level or cross-case."
          },
          "references": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/FindingReference"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "References",
            "description": "Other occurrences this finding points at (first occurrence, other filing). Null when not applicable."
          }
        },
        "type": "object",
        "required": [
          "check_id",
          "check_category",
          "severity",
          "summary"
        ],
        "title": "Finding",
        "description": "A single forensic finding produced by a check module.\n\ncheck_id is the stable identifier used by override_rules.yaml to match rules.\nBlues 2/3/4 must use check_ids that match entries in override_rules.yaml."
      },
      "FindingReference": {
        "properties": {
          "applicant_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Applicant Id"
          },
          "item_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Item Id"
          },
          "document": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Document"
          }
        },
        "type": "object",
        "title": "FindingReference",
        "description": "Pointer from a finding to another document / item / filing."
      },
      "FindingSeverity": {
        "type": "string",
        "enum": [
          "CRITICAL",
          "HIGH",
          "MEDIUM",
          "LOW",
          "INFO"
        ],
        "title": "FindingSeverity",
        "description": "Finding severity from individual check modules."
      },
      "ForensicResult": {
        "properties": {
          "applicant_id": {
            "type": "string",
            "title": "Applicant Id"
          },
          "case_type": {
            "type": "string",
            "title": "Case Type",
            "description": "Case type the request ran as. Always set; 'account_application' when the request did not name one.",
            "default": "account_application"
          },
          "verdict": {
            "$ref": "#/components/schemas/PolicyVerdict"
          },
          "verdict_message": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Message"
              },
              {
                "type": "null"
              }
            ],
            "description": "Operator-facing message (what + what_to_do) for the verdict band, resolved from the message catalog at response time. None only if resolution was not run."
          },
          "findings": {
            "items": {
              "$ref": "#/components/schemas/Finding"
            },
            "type": "array",
            "title": "Findings"
          },
          "aggregates": {
            "items": {
              "$ref": "#/components/schemas/Finding"
            },
            "type": "array",
            "title": "Aggregates",
            "description": "Composite weak-signal findings, the subset of findings[] with check_category == 'aggregate', mirrored here for client convenience. These are the SAME Finding objects as in findings[], not a separate source of truth."
          },
          "commercial_signals": {
            "items": {
              "$ref": "#/components/schemas/CommercialSignal"
            },
            "type": "array",
            "title": "Commercial Signals",
            "description": "Commercial / retention signals for the bank relationship team. Informational only, do NOT influence verdict."
          },
          "advisory_score": {
            "type": "integer",
            "maximum": 100,
            "minimum": 0,
            "title": "Advisory Score",
            "description": "0–100 advisory score. Secondary signal only, does NOT drive verdict."
          },
          "advisory_band": {
            "$ref": "#/components/schemas/AdvisoryBand",
            "description": "Advisory band derived from advisory_score. Informational."
          },
          "checker_version": {
            "type": "string",
            "title": "Checker Version",
            "description": "forensic_engine package version. Pins reproducibility."
          },
          "analysis_ts": {
            "type": "string",
            "format": "date-time",
            "title": "Analysis Ts",
            "description": "UTC timestamp of analysis."
          },
          "recommended_action": {
            "type": "string",
            "title": "Recommended Action",
            "description": "Human-readable next step, e.g. 'Request current payslip'.",
            "default": ""
          },
          "check_timings_ms": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "number"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Check Timings Ms",
            "description": "Per-check-block runtime in milliseconds, keyed by timing block name. Populated by the instrumented run_checks() aggregators. None when timing is unavailable."
          },
          "tenant_config_hash": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Tenant Config Hash",
            "description": "SHA-256 of the management TenantConfig active at analysis time. None when DB config is unavailable (file-mode or no config written)."
          },
          "checks_performed": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ChecksPerformed"
              },
              {
                "type": "null"
              }
            ],
            "description": "Every catalog check with its PASS / ATTENTION / N/A status, the complete result, not just the findings that fired. None when CaseData is unavailable (e.g. file-mode or a monkeypatched orchestrator)."
          },
          "extracted": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ExtractedData"
              },
              {
                "type": "null"
              }
            ],
            "description": "The facts the extraction layer read from each document (IBAN/SV masked). None when CaseData is unavailable."
          },
          "risk_indicator": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/RiskIndicator"
              },
              {
                "type": "null"
              }
            ],
            "description": "Case risk indicator (none | review | high). Null for account_application."
          },
          "consistency_result": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ConsistencyResult"
              },
              {
                "type": "null"
              }
            ],
            "description": "Case consistency roll-up (match | mismatch | not_checkable). Null for account_application."
          },
          "items": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/ItemResult"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Items",
            "description": "Per-item results for typed case types. Null for account_application."
          },
          "missing": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Missing",
            "description": "Case-level inputs the checks needed but did not get (e.g. 'documents.application', 'documents.membership_proof[sv.pdf]'); item-level gaps are in items[].missing. Null for account_application."
          }
        },
        "type": "object",
        "required": [
          "applicant_id",
          "verdict",
          "advisory_score",
          "advisory_band",
          "checker_version",
          "analysis_ts"
        ],
        "title": "ForensicResult",
        "description": "Top-level forensic result for one applicant, the API response envelope."
      },
      "GrantSettlementMasterData": {
        "properties": {
          "applicant": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MasterDataParty"
              },
              {
                "type": "null"
              }
            ]
          },
          "application_date": {
            "anyOf": [
              {
                "type": "string",
                "format": "date"
              },
              {
                "type": "null"
              }
            ],
            "title": "Application Date"
          },
          "funding_period": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MasterDataPeriod"
              },
              {
                "type": "null"
              }
            ]
          },
          "approved_target_countries": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Approved Target Countries",
            "description": "ISO 3166-1 alpha-2 country codes."
          },
          "approved_amount": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MasterDataAmount"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "additionalProperties": false,
        "type": "object",
        "title": "GrantSettlementMasterData",
        "description": "Applicant master data for grant_settlement. Every field is optional:\na check that needs a missing field reports `not_checkable` instead of failing."
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "ItemResult": {
        "properties": {
          "item_id": {
            "type": "string",
            "title": "Item Id"
          },
          "consistency_result": {
            "$ref": "#/components/schemas/ConsistencyResult"
          },
          "risk_indicator": {
            "$ref": "#/components/schemas/RiskIndicator"
          },
          "finding_refs": {
            "items": {
              "type": "integer"
            },
            "type": "array",
            "title": "Finding Refs",
            "description": "Indexes into ForensicResult.findings."
          },
          "missing": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Missing",
            "description": "Inputs the item's checks needed but did not get (e.g. 'documents.invoice[re1.pdf]', 'master_data.funding_period')."
          },
          "documents": {
            "additionalProperties": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "type": "object",
            "title": "Documents",
            "description": "Role → document ids assigned to this item: the uploaded filename, or the path inside the ZIP (e.g. '1/invoice.pdf')."
          }
        },
        "type": "object",
        "required": [
          "item_id",
          "consistency_result",
          "risk_indicator"
        ],
        "title": "ItemResult",
        "description": "Per-item result for typed case types (one item = one manifest item)."
      },
      "ManifestItem": {
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 64,
            "minLength": 1,
            "title": "Id",
            "description": "Item id, unique within the case."
          },
          "invoice": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Invoice"
          },
          "payment_proof": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Payment Proof"
          },
          "service_description": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Service Description"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id"
        ],
        "title": "ManifestItem",
        "description": "One cost item: its invoice(s), payment proof(s) and service description(s)."
      },
      "ManifestResponse": {
        "properties": {
          "applicant_id": {
            "type": "string",
            "title": "Applicant Id"
          },
          "case_type": {
            "type": "string",
            "title": "Case Type"
          },
          "manifest": {
            "$ref": "#/components/schemas/CaseManifest"
          }
        },
        "type": "object",
        "required": [
          "applicant_id",
          "case_type",
          "manifest"
        ],
        "title": "ManifestResponse"
      },
      "MasterDataAmount": {
        "properties": {
          "value": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "string",
                "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
              }
            ],
            "title": "Value"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "title": "Currency",
            "default": "EUR"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "value"
        ],
        "title": "MasterDataAmount"
      },
      "MasterDataParty": {
        "properties": {
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Name"
          },
          "address": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Address"
          },
          "iban": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Iban"
          },
          "uid": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Uid",
            "description": "VAT id (UID), e.g. ATU12345678."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "title": "MasterDataParty"
      },
      "MasterDataPeriod": {
        "properties": {
          "from": {
            "anyOf": [
              {
                "type": "string",
                "format": "date"
              },
              {
                "type": "null"
              }
            ],
            "title": "From"
          },
          "to": {
            "anyOf": [
              {
                "type": "string",
                "format": "date"
              },
              {
                "type": "null"
              }
            ],
            "title": "To"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "title": "MasterDataPeriod"
      },
      "Message": {
        "properties": {
          "what": {
            "type": "string",
            "title": "What",
            "description": "Plain-language description of what was found.",
            "default": ""
          },
          "what_to_do": {
            "type": "string",
            "title": "What To Do",
            "description": "Recommended next step for the operator.",
            "default": ""
          }
        },
        "type": "object",
        "title": "Message",
        "description": "Operator-facing message pair resolved from the default message catalog\n(docs/api/messages-catalog.json) by message_resolver.\n\n`what` is the factual finding in plain language; `what_to_do` is the\nrecommended next step for a bank back-office case reviewer. Locale- and\ntenant-resolved at response time (tenant overrides arrive in Wing B)."
      },
      "PolicyVerdict": {
        "properties": {
          "verdict": {
            "$ref": "#/components/schemas/VerdictType"
          },
          "reason_codes": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Reason Codes",
            "description": "Stable codes for the bank's policy engine, e.g. ['MRZ_CHECKSUM_FAIL']."
          },
          "override_rules_fired": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Override Rules Fired",
            "description": "IDs of override rules that triggered, e.g. ['I1', 'P3']."
          },
          "verdict_explanation": {
            "type": "string",
            "title": "Verdict Explanation",
            "description": "Human-readable tie-break / conflict resolution note.",
            "default": ""
          }
        },
        "type": "object",
        "required": [
          "verdict"
        ],
        "title": "PolicyVerdict",
        "description": "Primary verdict from the policy engine.\n\nProduced by evaluate_override_rules(). Drives all downstream actions."
      },
      "ReportRequest": {
        "properties": {
          "template": {
            "type": "string",
            "title": "Template"
          },
          "cover_page": {
            "type": "boolean",
            "title": "Cover Page",
            "default": true
          }
        },
        "type": "object",
        "title": "ReportRequest"
      },
      "RiskIndicator": {
        "type": "string",
        "enum": [
          "none",
          "review",
          "high"
        ],
        "title": "RiskIndicator",
        "description": "Case-type risk indicator, derived deterministically from the findings by rules\n(worst finding severity; not_checkable counts as review). A model never sets it."
      },
      "UploadDocumentResponse": {
        "properties": {
          "documents": {
            "items": {
              "$ref": "#/components/schemas/DocumentSummary"
            },
            "type": "array",
            "title": "Documents"
          }
        },
        "type": "object",
        "required": [
          "documents"
        ],
        "title": "UploadDocumentResponse"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "VerdictType": {
        "type": "string",
        "enum": [
          "REJECT",
          "ESCALATE",
          "PENDING",
          "CONDITIONAL",
          "PASS"
        ],
        "title": "VerdictType",
        "description": "Primary verdict from the policy engine."
      },
      "ZipJobResponse": {
        "properties": {
          "job_id": {
            "type": "string",
            "title": "Job Id"
          },
          "status": {
            "type": "string",
            "title": "Status"
          },
          "applicant_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Applicant Id"
          },
          "result": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ForensicResult"
              },
              {
                "type": "null"
              }
            ]
          },
          "intake_metadata": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ],
            "title": "Intake Metadata"
          },
          "error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Error"
          }
        },
        "type": "object",
        "required": [
          "job_id",
          "status"
        ],
        "title": "ZipJobResponse"
      },
      "ZipSubmitResponse": {
        "properties": {
          "job_id": {
            "type": "string",
            "title": "Job Id"
          },
          "status": {
            "type": "string",
            "title": "Status"
          },
          "status_url": {
            "type": "string",
            "title": "Status Url"
          }
        },
        "type": "object",
        "required": [
          "job_id",
          "status",
          "status_url"
        ],
        "title": "ZipSubmitResponse"
      },
      "_RtbeBody": {
        "properties": {
          "reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Reason"
          }
        },
        "type": "object",
        "title": "_RtbeBody"
      },
      "ProblemDetails": {
        "type": "object",
        "title": "ProblemDetails",
        "description": "Standard error body. Every 4xx/5xx response (except 429, see RateLimitError) carries at least `detail`. The stateless `/analyze` endpoint additionally includes `trace_id` on 5xx for support correlation.",
        "properties": {
          "detail": {
            "type": "string",
            "description": "Human-readable explanation of the failure."
          },
          "trace_id": {
            "type": "string",
            "description": "Correlation id; present on stateless /analyze 5xx responses only."
          }
        },
        "required": [
          "detail"
        ]
      },
      "RateLimitError": {
        "type": "object",
        "title": "RateLimitError",
        "description": "Body returned on HTTP 429. The `Retry-After` response header carries the same backoff in seconds.",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "rate_limit_exceeded"
            ]
          },
          "retry_after": {
            "type": "integer",
            "description": "Seconds until the next rate-limit window."
          }
        },
        "required": [
          "error",
          "retry_after"
        ]
      },
      "AnalysisCompletedEvent": {
        "type": "object",
        "title": "AnalysisCompletedEvent",
        "description": "Outbound `analysis_completed` webhook payload delivered to the tenant's configured callback URL.",
        "properties": {
          "event_type": {
            "type": "string",
            "enum": [
              "analysis_completed"
            ]
          },
          "event_id": {
            "type": "string",
            "description": "Stable unique id for this analysis event (replay/dedup key).",
            "example": "evt_2f1c9a40-0000-4000-8000-000000000001"
          },
          "external_applicant_id": {
            "type": "string",
            "description": "Echoed from the inbound submission.",
            "example": "APP-2026-000123"
          },
          "internal_applicant_id": {
            "type": "string",
            "format": "uuid"
          },
          "verdict": {
            "type": "string",
            "enum": [
              "REJECT",
              "ESCALATE",
              "PENDING",
              "CONDITIONAL",
              "PASS"
            ],
            "description": "Primary deterministic verdict. PENDING means extraction failed and the verdict is deferred."
          },
          "score": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 100,
            "description": "Advisory score 0-100 (== ForensicResult.advisory_score); informational, does NOT drive the verdict. May be null."
          },
          "top_findings": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "example": "KAZ_BACKDATING",
                  "description": "Stable check/finding code."
                },
                "severity": {
                  "type": "string",
                  "enum": [
                    "critical",
                    "high",
                    "medium",
                    "low",
                    "info"
                  ],
                  "description": "Lowercased severity band."
                },
                "summary": {
                  "type": "string",
                  "description": "One-line human-readable explanation."
                }
              },
              "required": [
                "code",
                "severity",
                "summary"
              ]
            },
            "description": "Up to 3 findings, most severe first."
          },
          "audit_reference": {
            "type": "string",
            "description": "audit_log row id; quote in support tickets.",
            "example": "8821"
          },
          "analyzed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When analysis completed."
          },
          "event_timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "When this webhook event was emitted."
          }
        },
        "required": [
          "event_type",
          "event_id",
          "external_applicant_id",
          "internal_applicant_id",
          "verdict",
          "event_timestamp"
        ]
      },
      "InboundWebhookAccepted": {
        "title": "InboundWebhookAccepted",
        "description": "202 response from the inbound webhook. Single-applicant, idempotent replay, or batch-enqueued shape.",
        "oneOf": [
          {
            "type": "object",
            "title": "single",
            "properties": {
              "internal_applicant_id": {
                "type": "string",
                "format": "uuid"
              },
              "status": {
                "type": "string",
                "enum": [
                  "analyzing"
                ]
              }
            },
            "required": [
              "internal_applicant_id",
              "status"
            ]
          },
          {
            "type": "object",
            "title": "idempotent_replay",
            "properties": {
              "internal_applicant_id": {
                "type": "string",
                "format": "uuid"
              },
              "status": {
                "type": "string",
                "enum": [
                  "analyzing"
                ]
              },
              "idempotency_replay": {
                "type": "boolean",
                "enum": [
                  true
                ]
              }
            },
            "required": [
              "internal_applicant_id",
              "status",
              "idempotency_replay"
            ]
          },
          {
            "type": "object",
            "title": "batch_enqueued",
            "properties": {
              "job_id": {
                "type": "string",
                "format": "uuid"
              },
              "status": {
                "type": "string",
                "enum": [
                  "batch_enqueued"
                ]
              }
            },
            "required": [
              "job_id",
              "status"
            ]
          }
        ]
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Per-request API key in the `Authorization: Bearer <token>` header, format `fsk_<8-char-prefix>_<secret>`. In production multi-tenant mode (Mode A) this is the tenant API key and the tenant identity is derived from it. In single-tenant compatibility mode (Mode B) it is the shared service token, paired with the `X-Tenant-ID` header. **Transport security:** mutual TLS (mTLS) is available as an optional connection-level hardening at the reverse proxy (outside this generated contract); it is not required by default, see the integration guide."
      },
      "tenantId": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Tenant-ID",
        "description": "Tenant selector. Honoured ONLY in single-tenant compatibility mode (Mode B); in production multi-tenant mode (Mode A) the tenant is derived from the bearer key and this header is ignored."
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "servers": [
    {
      "url": "https://aletheia.api-umbrella.io",
      "description": "Production"
    }
  ]
}
