Quick Start

Document Integrity

Finovox analyses each document's IT structure, so files must arrive unaltered. Connect the API upstream of any post-processing (resizing, flattening, re-printing) to preserve the original content.

Authentication

All API requests require an API key. You can generate yours from the Finovox dashboard.

Include your API key in the request headers:

api-key: your_api_key_here

API Endpoints

POSThttps://api-v2.finovox.com/case

POSThttps://api-v2.finovox.com/case/retrieve

Supported File Formats

• PDF (.pdf)
• JPEG (.jpg, .jpeg)
• PNG (.png)

Other office formats (.docx, .xlsx, …) and raster images (.tif, .heic, .webp) are also accepted; see Advanced Usage for the full matrix.

Your First Request

POST /case expects multipart/form-data with:

Field	Type	Required	Description
documents	File(s)	✅	Every file in the folder. Repeat the field per file — think of it as uploading a folder. Drop one or more .json files in the same list to send declared applicant context: a single JSON is treated as the folder form, multiple JSONs are merged into one entry per participant. form.json is free-form — see Folder Form.
payload	JSON object or string	✅	Requested analysis types and the use case to apply.

In this example we submit a rental folder and ask for the decision bundle only. We also drop a form.json alongside the PDFs with the declared applicant — it is optional, but passing what you already know helps the engine match documents to the right participant.

Python

import json
from pathlib import Path
import requests

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

# Put every file (PDFs + any form.json) in a single folder and ship
# them all under `documents` in one line — the API figures out which
# are documents and which are folder forms.
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"}),
}

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

Javascript

// npm install axios form-data
const fs = require('fs')
const path = require('path')
const axios = require('axios')
const FormData = require('form-data')

// Put every file (PDFs + any form.json) in a single folder and attach
// them all under `documents` — the API sorts out which are documents
// and which are folder forms.
const folder = 'samples/folder_julien_moreau'
const form = new FormData()
for (const name of fs.readdirSync(folder)) {
  const full = path.join(folder, name)
  if (fs.statSync(full).isFile()) form.append('documents', fs.createReadStream(full))
}
form.append('payload', JSON.stringify({ analyse_type: ['decision'], use_case: 'rental' }))

const { data } = await axios.post('https://api-v2.finovox.com/case', form, {
  headers: { 'api-key': 'YOUR_API_KEY_HERE', ...form.getHeaders() },
  timeout: 300_000,
})

console.log(data)

cURL

# Build one -F documents=@… arg per file in the folder, then fire a
# single request. form.json (if present) rides along like any other
# file — the API detects the .json extension server-side.
FOLDER="samples/folder_julien_moreau"
ARGS=()
for f in "$FOLDER"/*; do [ -f "$f" ] && ARGS+=(-F "documents=@$f"); done

curl -X POST "https://api-v2.finovox.com/case" \
  -H "api-key: YOUR_API_KEY_HERE" \
  "${ARGS[@]}" \
  -F 'payload={"analyse_type":["decision"],"use_case":"rental"}'

Request Timeout

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

Response

{
  "decision": {
    "status": "approved",
    "status_fraud": "low",
    "status_validation": "compliant"
  }
}

Field	Values	Meaning
status	approved | rejected	Global decision. Derived from status_fraud and status_validation: only status_fraud = low combined with status_validation = compliant yields approved; every other combination yields rejected.
status_fraud	high | medium | low	Anti-fraud. Risk of document tampering or falsification, aggregated across the folder.
status_validation	compliant | non_compliant	Validity. Use-case eligibility / business-rule outcome.

To also receive a hosted share link (with PDF download from the viewer), see Advanced Usage.

HTTP Status Codes

Code	Meaning	Action
200	Success	Synchronous result returned immediately.
202	Accepted	Asynchronous mode enabled, poll later with POST /case/retrieve.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	API key lacks Case Analysis access.
422	Unprocessable	No documents, unsupported extension, malformed JSON, or invalid/missing keys in payload.
429	Too Many Requests	Rate limit exceeded, slow down.
500	Server Error	Retry the request.