Asynchronous

For small folders, the synchronous flow is the simplest. For larger folders — many documents, or use cases that chain multiple LLM stages — switch to asynchronous mode to avoid timing out the caller.

Enable Async Mode

Set asynchronous: true in the request payload:

{
  "analyse_type": ["decision"],
  "use_case": "rental",
  "asynchronous": true
}

POST /case then returns immediately with 202 Accepted and a retrieval token:

{
  "retrieve_token": "gAAAAABo..."
}

Retrieve Endpoint

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

Poll with a JSON body containing the token:

{
  "retrieve_token": "gAAAAABo..."
}

While the folder is still running, the endpoint returns 202 with:

{
  "status": "processing",
  "run_id": "04_20_12_30_45_9f8d..."
}

Once the result is ready, the endpoint returns 200 with the same payload shape as the synchronous call. For the default analyse_type: ["decision"] mode:

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

note

Async results expire 60 minutes after the folder completes. Poll promptly and persist the payload once received.

HTTP Status Codes

POST /case/retrieve

Code	Meaning	Action
200	Success	Final async result is ready.
202	Processing	The folder is still running, keep polling.
401	Unauthorized	Invalid retrieve_token.
403	Forbidden	The token belongs to another authenticated user.
404	Not Found	The async run or token could not be found.
500	Server Error	The async folder failed and could not produce a final result.

Example

warning

If the result is not yet available the endpoint returns 202. Poll every 10–30 seconds until you receive 200.

Python

import json
import time
from pathlib import Path

import requests

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

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

# Point the client at your folder — PDFs and any JSON forms ride along
# under the same `documents` field.
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)}

submit = requests.post(
    f"{base_url}/case", headers=headers, files=files, data=data, timeout=120
)
submit.raise_for_status()
retrieve_token = submit.json()["retrieve_token"]
print(f"retrieve_token = {retrieve_token[:32]}...")

while True:
    retrieve = requests.post(
        f"{base_url}/case/retrieve",
        headers=headers,
        json={"retrieve_token": retrieve_token},
        timeout=120,
    )

    if retrieve.status_code == 200:
        print(retrieve.json())
        break

    if retrieve.status_code != 202:
        raise RuntimeError(retrieve.text)

    time.sleep(10)

Javascript

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

const headers = { 'api-key': 'YOUR_API_KEY_HERE' }

// Point at your folder — every file (PDFs + any JSON forms) is
// uploaded under `documents`.
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', asynchronous: true }),
)

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

const retrieveToken = submit.data.retrieve_token

while (true) {
  const retrieve = await axios.post(
    'https://api-v2.finovox.com/case/retrieve',
    { retrieve_token: retrieveToken },
    { headers, timeout: 120_000, validateStatus: () => true },
  )

  if (retrieve.status === 200) {
    console.log(retrieve.data)
    break
  }

  if (retrieve.status !== 202) {
    throw new Error(JSON.stringify(retrieve.data))
  }

  await new Promise((resolve) => setTimeout(resolve, 10_000))
}