Advanced Usage

Combining Response Modes

The analyse_type field accepts a list. Each value you include adds a single top-level key to the response; keys you do not request are omitted.

`analyse_type` value	Top-level response key	Description
`decision`	`decision`	Public decision bundle — status, fraud level, eligibility. Default when omitted.
`explanation`	`explanation`	Curated list of the alerts behind the decision (fraud, compliance, cross-document).
`share_link`	`share_link`	Hosted case-management viewer link with configurable access.

Example payload combining both:

{
  "analyse_type": ["decision", "share_link"],
  "use_case": "rental",
  "share_link_settings": {
    "access": "public",
    "password": ""
  }
}

Response shape for that request:

{
  "decision": {
    "status": "approved",
    "status_fraud": "low",
    "status_validation": "compliant"
  },
  "share_link": {
    "url": "https://app.finovox.com/share/case-management/XXXXX_YY=="
  }
}

Folder Form

The folder form is an optional JSON object carrying the declared applicant and folder context. It is not required, but passing what you already know helps the engine match documents to the right participant and flag discrepancies between declared values and what the documents actually show.

Free-form payload

form.json has no required schema. Structure it however makes sense for your pipeline — a single object, a list, or any nested shape. The engine reads it opaquely and uses whatever declared participant data it can recognise. The snippets below are examples, not a contract.

Send it as a regular file named form.json (or any *.json) inside the documents multipart field — the API detects the .json extension and treats the file as the folder form. To describe several participants, just drop multiple JSON files into the folder (one per applicant, co-applicant, guarantor, …) and the API merges them into a single form.json array — one entry per participant. The call stays a single folder upload:

samples/folder_julien_moreau/
├── id.pdf
├── payslip.pdf
├── applicant.json        ← role: primary
└── co_applicant.json     ← role: co_applicant

from pathlib import Path

folder = Path("samples/folder_julien_moreau")
files = [("documents", (f.name, f.open("rb"))) for f in folder.iterdir() if f.is_file()]
data = {
    "payload": json.dumps({"analyse_type": ["decision"], "use_case": "rental"}),
}

Example shapes

Any of the shapes below (and anything in between) is acceptable. Pick whatever keys are natural for your domain — the engine does not validate field names.

Flat single applicant

{
  "full_name": "Julien Moreau",
  "birthdate": "1990-03-11",
  "monthly_income_declared": 3400,
  "rental_budget": 320,
  "notes": "Prefers unfurnished."
}

List of participants (same result as dropping several JSON files)

[
  { "role": "primary", "full_name": "Julien Moreau", "monthly_income_declared": 3400 },
  { "role": "co_applicant", "full_name": "Claire Moreau" },
  { "role": "guarantor", "full_name": "Parent Moreau", "notes": "Covers 6 months rent." }
]

Nested under applicants / participants / entries / items

{
  "applicants": [
    { "full_name": "Julien Moreau" },
    { "full_name": "Claire Moreau" }
  ],
  "folder_notes": "Car loan simulation for compact SUV."
}

Additional keys you already have in your CRM (policy numbers, loan amounts, incident details, KYB data, …) can sit alongside the examples — they travel with the folder as-is.

Full example

Drop every file — PDFs plus any number of JSON forms — into a single local folder, then ship the whole folder in one request:

samples/folder_julien_moreau/
├── cni.pdf
├── payslip_1.pdf
├── payslip_2.pdf
├── payslip_3.pdf
├── quittance_1.pdf
├── quittance_2.pdf
├── quittance_3.pdf
├── applicant.json        ← free-form, one per participant
└── co_applicant.json

import json
from pathlib import Path

import requests

url = "https://api-v2.finovox.com/case"
headers = {"api-key": "YOUR_API_KEY_HERE"}

payload = {
    "analyse_type": ["decision", "share_link"],
    "use_case": "rental",
    "share_link_settings": {"access": "public", "password": ""},
}

# Iterate the folder — every file goes under `documents`. JSON files are
# auto-detected as folder forms and merged into form.json.
folder = Path("samples/folder_julien_moreau")
files = [("documents", (f.name, f.open("rb"))) for f in folder.iterdir() if f.is_file()]
data = {"payload": json.dumps(payload)}

response = requests.post(url, headers=headers, files=files, data=data, timeout=300)
response.raise_for_status()
print(response.json())

Explanation

When explanation is in analyse_type, the response exposes an explanation array listing every alert raised across the folder. It is the detail behind the decision verdict — the individual findings that drove the fraud level and eligibility outcome — without you having to parse per-document payloads.

Each entry is tagged with a source:

`source`	What it covers
`fraud`	Tampering / falsification signals on a single document (software, metadata, datastructure, visual, coherence, community).
`compliance`	Document quality and business-rule checks (quality, expected category, expected fields, business control).
`cross_document`	Inconsistencies detected across documents in the folder (e.g. an address or name mismatch between files).

Every entry carries bilingual (en / fr) text so you can surface either language without a second call.

Example payload:

{
  "analyse_type": ["decision", "explanation"],
  "use_case": "rental"
}

Response shape for that request:

{
  "decision": {
    "status": "rejected",
    "status_fraud": "medium",
    "status_validation": "compliant"
  },
  "explanation": [
    {
      "source": "fraud",
      "data": { "en": "The document was last edited with image-editing software.", "fr": "Le document a été modifié avec un logiciel de retouche d'image." },
      "source_documents": ["payslip.pdf"]
    },
    {
      "source": "cross_document",
      "data": { "en": "The address differs between the lease and the proof of residence.", "fr": "L'adresse diffère entre le bail et le justificatif de domicile." },
      "source_documents": ["lease.pdf", "proof_of_residence.pdf"]
    }
  ]
}

Each entry exposes:

source — fraud, compliance, or cross_document (see table above).
data — bilingual { en, fr } text: the short, reviewer-facing message explaining the alert.
source_documents — the file(s) the alert relates to. For cross_document alerts this lists every document involved in the inconsistency.

When no alerts are raised, explanation is an empty array.

When share_link is in analyse_type, the response exposes share_link.url — a hosted viewer link that renders the full case-management report in a browser. The viewer also lets reviewers download the PDF evidence report directly from the frontend, so there is no API decoding required.

Configure access with share_link_settings in the request payload:

access: who can open the link.
- user: only the caller who made the request.
- organization: any user in the caller's organisation.
- public: anyone with the link.
password: optional passphrase prompted on the viewer. Omit or pass an empty string to disable.
ttl: lifetime of the link in seconds. Defaults to 30 days (2 592 000 seconds).

Language Parameter

Append ?lang=fr or ?lang=en to the returned URL to force the viewer language. English is the default.

{
  "share_link": {
    "url": "https://app.finovox.com/share/case-management/XXXXX_YY==?lang=fr"
  }
}

Request Timeout

Request timeout

Case Analysis runs several analysis and decision stages. Set a request timeout of at least 300 seconds for synchronous calls. For larger folders use asynchronous requests.

Combining Response Modes​

Folder Form​

Example shapes​

Full example​

Explanation​

Share Link​

Language Parameter​

Request Timeout​