Documents

RecovAI reads the documents on a case (agreements, statements, filings) to build its picture of the account. Uploading the right documents is usually what moves a case forward.

Method	Path	What it does
`POST`	`/cases/{id}/documents`	Upload a document
`GET`	`/cases/{id}/documents`	List a case’s documents
`GET`	`/documents/{docId}/file`	Download a document

Upload a document

POST/cases/{id}/documentsmultipart/form-dataChanges dataAPI key

Field	Type	Required	Description
`file`	file	yes	PDF, PNG, JPEG or TIFF, up to 25 MB.
`type`	string	yes	One of the document types.

curl https://api.recovai.ai/cases/5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a/documents \
  -H "X-API-Key: $RECOVAI_API_KEY" \
  -F type=bank_statement \
  -F file=@statement-2026-09.pdf

<?php
$ch = curl_init('https://api.recovai.ai/cases/5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a/documents');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => [
        'type' => 'bank_statement',
        'file' => new CURLFile('statement-2026-09.pdf', 'application/pdf'),
    ],
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('RECOVAI_API_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$result = json_decode($body, true);
if ($status >= 400) {
    throw new RuntimeException($result['error'] . ': ' . ($result['details'] ?? ''));
}

import { readFile } from 'node:fs/promises';

const body = new FormData();
body.append('type', 'bank_statement');
body.append('file', new Blob([await readFile('statement-2026-09.pdf')], { type: 'application/pdf' }), 'statement-2026-09.pdf');

const res = await fetch('https://api.recovai.ai/cases/5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a/documents', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.RECOVAI_API_KEY },
  body,
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.details ?? ''}`);

import os
import requests

r = requests.post(
    "https://api.recovai.ai/cases/5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a/documents",
    headers={"X-API-Key": os.environ["RECOVAI_API_KEY"]},
    data={
        "type": "bank_statement",
    },
    files={"file": ("statement-2026-09.pdf", open("statement-2026-09.pdf", "rb"), "application/pdf")},
    timeout=60,
)
data = r.json()
if not r.ok:
    raise RuntimeError(f"{data['error']}: {data.get('details', '')}")

Response `201 Created`

{
  "doc": {
    "id": "0d9e8f7a-6b5c-4d3e-a2f1-0e9d8c7b6a50",
    "case_id": "5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a",
    "type": "bank_statement",
    "status": "uploaded",
    "ocr_status": "not_started",
    "extraction_status": "not_started",
    "original_file_name": "statement-2026-09.pdf",
    "mime_type": "application/pdf",
    "created_at": "2026-10-14T15:44:12.000Z"
  },
  "duplicate_of_case_id": null,
  "readiness": "ready_for_extraction"
}

readiness is the case’s readiness after the upload.
If the identical file is already on another case, it is still uploaded, and duplicate_of_case_id names that case.
Uploading the same file twice to the same case is refused with 409 document_already_on_case.

Errors

400 file_required, 404 case_not_found, 409 document_already_on_case, 413 upload_rejected (too large), 415 unsupported_file_type, 422 validation_error (unknown type).

List a case’s documents

GET/cases/{id}/documentsRead onlyAPI key

Example

curl https://api.recovai.ai/cases/5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a/documents \
  -H "X-API-Key: $RECOVAI_API_KEY"

<?php
$ch = curl_init('https://api.recovai.ai/cases/5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a/documents');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('RECOVAI_API_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$result = json_decode($body, true);
if ($status >= 400) {
    throw new RuntimeException($result['error'] . ': ' . ($result['details'] ?? ''));
}

const res = await fetch('https://api.recovai.ai/cases/5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a/documents', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.RECOVAI_API_KEY },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.details ?? ''}`);

import os
import requests

r = requests.get(
    "https://api.recovai.ai/cases/5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a/documents",
    headers={"X-API-Key": os.environ["RECOVAI_API_KEY"]},
    timeout=60,
)
data = r.json()
if not r.ok:
    raise RuntimeError(f"{data['error']}: {data.get('details', '')}")

Returns the documents currently active on the case, newest first.

{
  "documents": [
    {
      "id": "0d9e8f7a-6b5c-4d3e-a2f1-0e9d8c7b6a50",
      "type": "bank_statement",
      "status": "verified",
      "verified": true,
      "original_file_name": "statement-2026-09.pdf",
      "mime_type": "application/pdf",
      "created_at": "2026-10-14T15:44:12.000Z"
    }
  ]
}

Download a document

GET/documents/{docId}/fileRead onlyAPI key

Streams the stored file with its original content type. Add ?download=1 to receive it as an attachment; downloads are recorded in your workspace audit log.

curl "https://api.recovai.ai/documents/0d9e8f7a-6b5c-4d3e-a2f1-0e9d8c7b6a50/file?download=1" \
  -H "X-API-Key: $RECOVAI_API_KEY" \
  -o statement.pdf

<?php
$ch = curl_init('https://api.recovai.ai/documents/0d9e8f7a-6b5c-4d3e-a2f1-0e9d8c7b6a50/file?download=1');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('RECOVAI_API_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException("Download failed: $status");
}
file_put_contents('statement.pdf', $body);

import { writeFile } from 'node:fs/promises';

const res = await fetch('https://api.recovai.ai/documents/0d9e8f7a-6b5c-4d3e-a2f1-0e9d8c7b6a50/file?download=1', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.RECOVAI_API_KEY },
});
if (!res.ok) throw new Error(`Download failed: ${res.status}`);
await writeFile('statement.pdf', Buffer.from(await res.arrayBuffer()));

import os
import requests

r = requests.get(
    "https://api.recovai.ai/documents/0d9e8f7a-6b5c-4d3e-a2f1-0e9d8c7b6a50/file?download=1",
    headers={"X-API-Key": os.environ["RECOVAI_API_KEY"]},
    timeout=60,
)
r.raise_for_status()
with open("statement.pdf", "wb") as f:
    f.write(r.content)

Errors

404 file_not_found.

Document types

Value	Document
`contract`	The agreement.
`ucc_filing`	UCC filing.
`bank_statement`	Bank statement.
`billing_statement`	Billing statement.
`transaction_history`	Transaction history.
`letter_of_representation`	Letter of representation.
`letter_of_agency`	Letter of agency.
`proof_of_assignment`	Proof of assignment.
`state_disclosure`	State disclosure.
`correspondence`	Correspondence.
`return_receipt`	Return receipt.
`redacted_packet`	Redacted packet.
`generated_notice`	A notice generated outside RecovAI.
`other`	Anything else.

Documents

Upload a document

Response 201 Created

Errors

List a case’s documents

Example

Download a document

Errors

Document types

Response `201 Created`