Upload Bank Statement

Endpoint Overview

POST /api/v1/bank/statement/upload

Description

This API endpoint allows you to upload a bank statement in PDF format for analysis. The service processes the uploaded statement and returns a unique client ID that can be used to track and retrieve the analysis results. This endpoint is part of Surepass's financial document processing capabilities, enabling automated extraction and verification of financial information from bank statements.

Key Benefits

Streamlined document processing with simple PDF upload functionality

Immediate response with a unique tracking identifier

Secure handling of sensitive financial documents

Integration with Surepass's comprehensive financial analysis ecosystem

Use Cases

Financial Services

Fintech

Enterprise

Loan application processing requiring income and transaction verification

Credit risk assessment through bank statement analysis

Account opening procedures requiring financial history verification

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication (JWT format)
Content-Type	Yes	Must be set to `multipart/form-data` for file upload

Request Body

Parameter	Type	Required	Description
file	File (PDF)	Yes	The bank statement document in PDF format to be uploaded and analyzed

Example Request

# This is a multipart/form-data request with a PDF file upload
# The file parameter contains the binary PDF data
'file=@"/path/to/file"' \

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the response data
data.client_id	String	Unique identifier for tracking the uploaded statement analysis
status_code	Number	HTTP status code indicating the result of the operation
success	Boolean	Indicates whether the operation was successful
message	String	Human-readable description of the operation result
message_code	String	Machine-readable code representing the operation result

Example Successful Response

{
    "data": {
        "client_id": "statement_analysis_sJRzpcpuOAnnjDYHOtPJ"
    },
    "status_code": 200,
    "success": true,
    "message": "Successfully Uploaded",
    "message_code": "success"
}

Possible Error Responses

Invalid File

Authentication Error

{
    "status_code": 422,
    "success": false,
    "message": "Verification Failed.",
    "message_code": "verification_failed"
}

The provided PAN number does not match the required format or contains invalid characters.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement token refresh mechanisms to handle token expiration

Use HTTPS for all API communications to ensure data encryption in transit

Implement proper error handling for authentication failures

User Experience Guidelines

Provide clear feedback to users during the upload process with progress indicators

Implement file size and format validation before submission to prevent errors

Store the returned client_id securely for subsequent API calls

Display meaningful error messages to users when upload issues occur

Code Samples

cURL

Python

Node.js

Related APIs

Bank Statement Analysis API: Retrieve detailed analysis of the uploaded bank statement

Bank Statement Verification API: Verify the authenticity of uploaded bank statements

Transaction Categorization API: Get categorized transaction data from bank statements

Compliance and Legal Considerations

When handling bank statements, ensure you have proper consent from users to process their financial information. Bank statements contain sensitive personal and financial data that may be subject to data protection regulations such as GDPR, CCPA, or other regional privacy laws. Ensure your application's privacy policy clearly discloses how this information will be used and stored.

{ "data": { "client_id": "statement_analysis_sJRzpcpuOAnnjDYHOtPJ" }, "status_code": 200, "success": true, "message": "Successfully Uploaded", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Upload Statement

Upload Bank Statement#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses