Key Benefits

• Flexible File Formats: Upload individual PDF bank statements or ZIP archives containing multiple PDFs — choose the format that fits your workflow.
• Batch Efficiency: Submit multiple files or a single ZIP in one request, reducing integration complexity and API round-trips.
• Date-Range Scoping: Filter analysis to a precise period using from_date and to_date, ensuring only relevant transactions are processed.
• Email Notifications: Automated result delivery to a specified email address keeps stakeholders informed without polling.
• Scalable Integration: Built for fintech, lending, and compliance use cases that routinely handle large statement volumes.

ZIP File Guidelines

• The ZIP must contain only PDF files at the root level or in subdirectories.
• Nested ZIPs (a ZIP inside a ZIP) are not supported.
• Ensure PDFs inside the ZIP are not password-protected.
• You may mix individual PDFs and ZIP archives in the same request (e.g., two .pdf files and one .zip).
  :::

Example Request (PDF files)

curl --location 'https://api.finpass.ai/api/v1/services/bsa/upload-statements-batch' \
  --header 'x-api-key: <X_API_KEY>' \
  --header 'x-api-secret: <X_API_SECRET>' \
  --form 'files=@"/path/to/statement-1.pdf"' \
  --form 'files=@"/path/to/statement-2.pdf"' \
  --form 'email="user@example.com"' \
  --form 'from_date="2024-04-01"' \
  --form 'to_date="2025-03-31"'

Example Request (ZIP archive)

curl --location 'https://api.finpass.ai/api/v1/services/bsa/upload-statements-batch' \
  --header 'x-api-key: <X_API_KEY>' \
  --header 'x-api-secret: <X_API_SECRET>' \
  --form 'files=@"/path/to/statements-bundle.zip"' \
  --form 'email="user@example.com"' \
  --form 'from_date="2024-04-01"' \
  --form 'to_date="2025-03-31"'

Example Request (mixed PDF and ZIP)

curl --location 'https://api.finpass.ai/api/v1/services/bsa/upload-statements-batch' \
  --header 'x-api-key: <X_API_KEY>' \
  --header 'x-api-secret: <X_API_SECRET>' \
  --form 'files=@"/path/to/statement-1.pdf"' \
  --form 'files=@"/path/to/statements-bundle.zip"' \
  --form 'email="user@example.com"' \
  --form 'from_date="2024-04-01"' \
  --form 'to_date="2025-03-31"'

The API returns a JSON response confirming receipt and processing initiation of the batch.

Example Successful Response

{
  "status": "success",
  "message": "Batch uploaded successfully. Analysis results will be sent to the provided email.",
  "batch_id": "bsa_batch_a1b2c3d4e5f6",
  "files_received": 2,
  "email": "user@example.com",
  "from_date": "2024-04-01",
  "to_date": "2025-03-31"
}

Possible Error Responses

Integration Best Practices

Code Samples

Upload a ZIP archive containing multiple PDFs

curl --location 'https://api.finpass.ai/api/v1/services/bsa/upload-statements-batch'
--header 'x-api-key: <X_API_KEY>'
--header 'x-api-secret: <X_API_SECRET>'
--form 'files=@"/path/to/statements-bundle.zip"'
--form 'email="user@example.com"'
--form 'from_date="2024-04-01"'
--form 'to_date="2025-03-31"'

</Tab>
<Tab title="Python">
```python
import requests

url = "https://api.finpass.ai/api/v1/services/bsa/upload-statements-batch"

headers = {
    "x-api-key": "<X_API_KEY>",
    "x-api-secret": "<X_API_SECRET>",
}

# Option 1: Upload individual PDF files
files = [
    ("files", ("statement-1.pdf", open("/path/to/statement-1.pdf", "rb"), "application/pdf")),
    ("files", ("statement-2.pdf", open("/path/to/statement-2.pdf", "rb"), "application/pdf")),
]

# Option 2: Upload a ZIP archive containing multiple PDFs
# files = [
#     ("files", ("statements-bundle.zip", open("/path/to/statements-bundle.zip", "rb"), "application/zip")),
# ]

# Option 3: Mix of PDFs and a ZIP
# files = [
#     ("files", ("statement-1.pdf", open("/path/to/statement-1.pdf", "rb"), "application/pdf")),
#     ("files", ("statements-bundle.zip", open("/path/to/statements-bundle.zip", "rb"), "application/zip")),
# ]

data = {
    "email": "user@example.com",
    "from_date": "2024-04-01",
    "to_date": "2025-03-31",
}

response = requests.post(url, headers=headers, files=files, data=data)

print(response.status_code)
print(response.json())

const url = "https://api.finpass.ai/api/v1/services/bsa/upload-statements-batch";

const form = new FormData();

// Option 1: Upload individual PDF files
form.append("files", fs.createReadStream("/path/to/statement-1.pdf"), "statement-1.pdf");
form.append("files", fs.createReadStream("/path/to/statement-2.pdf"), "statement-2.pdf");

// Option 2: Upload a ZIP archive containing multiple PDFs
// form.append("files", fs.createReadStream("/path/to/statements-bundle.zip"), {
// filename: "statements-bundle.zip",
// contentType: "application/zip",
// });

form.append("email", "user@example.com");
form.append("from_date", "2024-04-01");
form.append("to_date", "2025-03-31");

axios
.post(url, form, {
headers: {
"x-api-key": "<X_API_KEY>",
"x-api-secret": "<X_API_SECRET>",
...form.getHeaders(),
},
})
.then((response) => {
console.log(response.status);
console.log(response.data);
})
.catch((error) => {
console.error(error.response?.data || error.message);
});

</Tab>
<Tab title="PHP">
```php
<?php

$url = "https://api.finpass.ai/api/v1/services/bsa/upload-statements-batch";

$curl = curl_init();

// Option 1: Upload individual PDF files
$postFields = [
    'files[0]' => new CURLFile('/path/to/statement-1.pdf', 'application/pdf', 'statement-1.pdf'),
    'files[1]' => new CURLFile('/path/to/statement-2.pdf', 'application/pdf', 'statement-2.pdf'),
    'email'     => 'user@example.com',
    'from_date' => '2024-04-01',
    'to_date'   => '2025-03-31',
];

// Option 2: Upload a ZIP archive containing multiple PDFs
// $postFields = [
//     'files[0]' => new CURLFile('/path/to/statements-bundle.zip', 'application/zip', 'statements-bundle.zip'),
//     'email'     => 'user@example.com',
//     'from_date' => '2024-04-01',
//     'to_date'   => '2025-03-31',
// ];

curl_setopt_array($curl, [
    CURLOPT_URL            => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $postFields,
    CURLOPT_HTTPHEADER     => [
        'x-api-key: <X_API_KEY>',
        'x-api-secret: <X_API_SECRET>',
    ],
]);

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo "HTTP Status: $httpCode\n";
echo $response;