Finpass API Collection
  1. Bank Statement Analyser
  • Introduction
  • Bank Statement Analyser
    • Upload Statement
      POST
    • Statement Result
      GET
  1. Bank Statement Analyser

Upload Statement

POST
/api/v1/services/bsa/upload-statement

Bank Statement Upload API#

Endpoint Overview
POST /api/v1/services/bsa/upload-statement

Description#

The Bank Statement Upload API enables seamless uploading of bank statements for automated analysis and processing. This endpoint accepts bank statement files in various formats and initiates an asynchronous processing pipeline that extracts, categorizes, and analyzes financial transaction data.
Upon successful upload, the API returns a unique document identifier (doc_id) that can be used to track processing status and retrieve analysis results. The Bank Statement Analysis (BSA) service leverages advanced parsing technologies to extract structured data from uploaded statements, providing valuable insights for credit assessment, financial health evaluation, and fraud detection.
Key Benefits
Automated Data Extraction: Eliminates manual data entry by automatically extracting transaction data from bank statements
Asynchronous Processing: Non-blocking upload ensures quick response times while complex analysis happens in the background
Multi-Format Support: Accepts various file formats including PDF, images, and scanned documents
Secure Handling: Bank statements are processed with enterprise-grade security and encryption

Use Cases#

Lending & Credit
Financial Services
Risk & Compliance
Loan Underwriting: Upload applicant bank statements to assess income stability, spending patterns, and creditworthiness for loan approval decisions
Credit Line Assessment: Analyze cash flow patterns to determine appropriate credit limits for business or personal credit products
Income Verification: Validate declared income against actual bank deposits for mortgage or personal loan applications

Technical Implementation#

1
Authentication
All API requests require authentication using API credentials provided in the request headers. Authentication follows these steps:
1.
Obtain API Credentials: Register with FinPass to receive your API Key and API Secret.
2.
Include in Request Headers: Add both credentials to your request headers.
3.
Secure Storage: Store your credentials securely and never expose them in client-side code.
API Base URL:
Production: https://api.finpass.ai
Required Headers:
HeaderDescription
X-API-KeyYour unique API key provided by FinPass
X-API-SecretYour API secret for request authentication
2
Request Parameters

Request Headers#

HeaderRequiredDescription
X-API-KeyYesYour unique API key for authentication
X-API-SecretYesYour API secret for secure request validation
Content-TypeYesMust be multipart/form-data for file uploads

Request Body#

This endpoint accepts multipart/form-data with the following parameters:
ParameterTypeRequiredDescription
fileFileYesThe bank statement file to be uploaded. Supported formats include PDF, PNG, JPG, and JPEG. Maximum file size limits may apply.

Example Request Structure#

Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="file"; filename="bank_statement.pdf"
Content-Type: application/octet-stream

[Binary file content]
--boundary--
3
Process Response

Response Parameters#

ParameterTypeDescription
successBooleanIndicates whether the upload request was successful
status_codeIntegerHTTP status code of the response
messageStringHuman-readable message describing the result
dataObjectContainer object for response data
data.doc_idStringUnique identifier for the uploaded document, used to track processing status and retrieve results
data.client_idStringClient-specific identifier associated with the bank statement
data.statusStringCurrent processing status of the uploaded document (e.g., "processing", "completed", "failed")

Example Successful Response#

{
    "success": true,
    "status_code": 200,
    "message": "Bank statement uploaded successfully",
    "data": {
        "doc_id": "svclog_69753dcc_d9e510428e00d4efe9247072",
        "client_id": "bank_statement_bd24ad80515b",
        "status": "processing"
    }
}

Possible Error Responses#

Authentication Error
Invalid File Error
File Size Error
{
    "success": false,
    "status_code": 401,
    "message": "Invalid API credentials",
    "data": null
}
This error occurs when the X-API-Key or X-API-Secret headers are missing, invalid, or expired. Verify your credentials and ensure they are correctly included in the request headers.

Integration Best Practices#

Security Recommendations
Secure Credential Storage: Store your X-API-Key and X-API-Secret in environment variables or a secure secrets manager—never hardcode them in your application
HTTPS Only: Always use HTTPS when communicating with the API to ensure data encryption in transit
Server-Side Calls: Make API calls from your backend server only; never expose API credentials in client-side code or mobile applications
File Validation: Validate file types and sizes on your end before uploading to prevent unnecessary API calls and potential security issues
Access Logging: Maintain audit logs of all bank statement uploads for compliance and security monitoring purposes
User Experience Guidelines
Progress Indicators: Display upload progress to users, especially for larger files, to improve perceived performance
Clear Instructions: Provide users with clear guidelines on acceptable file formats and quality requirements before upload
Error Handling: Implement user-friendly error messages that guide users to resolve issues (e.g., "Please upload a PDF or image file")
Status Updates: Use the doc_id to poll for processing status and keep users informed about the analysis progress
Retry Mechanism: Implement automatic retry logic with exponential backoff for transient failures to improve reliability

Code Samples#

cURL
Python
Node.js
Java
PHP
Compliance and Legal Considerations
Data Privacy: Bank statements contain sensitive personal and financial information. Ensure your application complies with applicable data protection regulations such as GDPR, CCPA, or local financial data protection laws.
User Consent: Obtain explicit consent from users before uploading their bank statements for analysis. Clearly communicate how their financial data will be processed and stored.
Data Retention: Implement appropriate data retention policies. Financial data should be stored only as long as necessary for the stated purpose and securely deleted thereafter.
PCI DSS Compliance: While bank statements don't contain full card numbers, ensure your overall data handling practices align with PCI DSS requirements if you process any payment card data.
Audit Trail: Maintain comprehensive audit logs of all bank statement uploads and access for regulatory compliance and dispute resolution purposes.
Third-Party Disclosure: Review and comply with any restrictions on sharing analyzed financial data with third parties.

Request

Header Params

Body Params multipart/form-data

Responses

🟢200
application/json
Body

Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://api.finpass.ai/api/v1/services/bsa/upload-statement' \
--header 'X-API-Key: LG8zVXK1MZv1jP6i4l6QZQ2nD9kLTvFWipV_anPvacE' \
--header 'X-API-Secret: M5RwMtvbYGqAGZpG8d223xkEq1298kjcGGpJ7s7_-Iv-T80x2l2YcaDSLAmoGkDn' \
--form 'file=@""'
Response Response Example
{
    "success": true,
    "status_code": 200,
    "message": "Bank statement uploaded successfully",
    "data": {
        "doc_id": "svclog_69753dcc_d9e510428e00d4efe9247072",
        "client_id": "bank_statement_bd24ad80515b",
        "status": "processing"
    }
}
Previous
Bank Statement Analyser
Next
Statement Result
Built with