👋 Introduction

Case Analysis analyses a folder — a set of documents uploaded together — against a pre-configured use case, and returns a single decision package instead of per-document signals.

Reach for it when you are handling a specific business use case involving multiple documents and multiple participants — a rental application with a tenant and a guarantor, a credit file with co-borrowers, an onboarding package with a company and its beneficial owners. The API consolidates the whole folder into one decision so you don't have to stitch per-document signals back together yourself.

For single-document fraud analysis or raw data extraction, use the core Document Analysis API instead.

Overview

A single request to POST /case uploads the folder and returns complementary outputs:

1. Decision

A consolidated ruling on the folder, built from three signals:

• Anti-fraud (status_fraud) — aggregated risk of tampering or falsification (low / medium / high).
• Validity (status_validation) — use-case eligibility / business-rule outcome (compliant / non_compliant).
• Global decision (status) — derived from the two above. Only Anti-fraud = low combined with Validity = compliant yields approved; every other combination yields rejected.

See decision response →

2. Explanation

A curated list of every alert raised across the folder, so you can see why the decision came out the way it did without parsing per-document payloads. Each alert is tagged by source:

• fraud — tampering / falsification signals on a single document (software, metadata, structure, visual, coherence, community).
• compliance — document quality and business-rule checks (expected category, expected fields, business control, quality).
• cross_document — inconsistencies detected across documents in the folder (e.g. an address or name that does not match between two files).

Each alert exposes its source, the bilingual (en / fr) data text explaining it, and the source_documents it relates to.

See explanation response →

3. Share Link

A hosted viewer link so reviewers can open the full case-management report in a browser with configurable access (public / organisation / user) and an optional password. The PDF evidence report is downloadable directly from the viewer — no API decoding required.

See share-link options →

Each output is opt-in: the analyse_type field controls which top-level keys the response exposes.

Available Use Cases

A use case selects the business rules, KPIs and decision prompts applied to the folder. Pick one by passing its id in the request payload.

id	Label	What it analyses
rental	Rental application	Residential rental review focused on tenant stability, income, rent receipts, and guarantor coverage.
credit	Credit application	Solvency assessment for a credit request: income, expenses, existing loans, and guarantees.
mortgage	Mortgage application	Home purchase or refinance file: financing needs, down payment, debt service, and collateral.
insurance_claim	Insurance claim	Qualification of a motor or property claim: policy, circumstances, damages, and estimates.
supplier_onboarding	Onboarding (KYC / KYB)	Legal identity, beneficial owners, insurance, tax clearance, and payment details.

Discover use cases at runtime

Rather than hard-coding the list above, you can call GET /case/use-cases to retrieve the catalog the API actually exposes for your organisation, including localized labels and descriptions. The response is { use_cases: [{ id, label, description }], default_use_case }.

Scenarios

Inside a use case, the engine auto-detects a scenario — the applicant's primary situation — and uses it to pick the required-document list and the validity rules. For a rental folder this is typically the employment situation of the primary applicant (CDI, student, retired, freelancer, …).

You do not pick the scenario; the engine infers it from the folder form and the documents themselves. If nothing applies, it falls back to undetermined and downstream checks degrade gracefully.

Why it matters

• Required documents and validity rules change with the scenario. A CDI rental file requires payslips and an employment contract; a student file requires a school certificate instead — same use case, different verdict on the same files.
• Scenarios can be restricted per organisation. Finovox can narrow the active scenarios for your tenant (e.g. only CDI / student / retired for rental). Out-of-scope situations roll up to undetermined.

The selected scenario travels in the canonical case payload visible in the share-link viewer. It is not surfaced in the compact decision bundle.

🚀 Next Steps

Ready to integrate? Head to the Quick Start for authentication, your first request, and the decision response shape.