Bank Statement Analysis API

Objective

The Bank Statement Analysis API extracts transactions from bank statements using OCR (Optical Character Recognition) in JSON format. It can also analyze and produce insights from them in the form of a JSON.

Input	Output
The user's bank statement in PDF format	It contains the following information: Transactions Transaction Threshold Fraud Checks

API URL

https://ind-engine.thomas.hyperverge.co/v1/bank_statement_analysis

API Endpoint

bank_statement_analysis

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format, and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - POST

Headers

Header	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	The media type for the request payload.	multipart/form-data
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey.	This should be both unique and easily associated with the user's journey in your application(s).

Inputs

The following table provides the details of the fields required for the API's request body.

Parameter	Mandatory or Optional	Description	Allowed Values	Default Values
pdf	Mandatory	The Bank Statement PDF file on which you want to perform the OCR	Not Applicable	Not Applicable
password	Optional	Password for opening the bank statement (if it's password protected)	string	Not Applicable
enableFraudChecks	Optional	Enable checks for suspicious or fraudulent transactions	yes / no	no
extractEntities	Optional	Extract named entities like account holder, bank name, etc.	yes / no	no
country	Optional	Country code of the bank statement (ISO 3166-1 alpha-3 format preferred)	ind, usa, etc.	ind
returnTransactions	Optional	Return detailed transaction data	yes / no	yes
transactionThreshold	Optional	Minimum transaction amount to include in results	numeric (e.g., 0)	0
formatDateYearFirst	Optional	Indicates if date format in statement is YYYY-MM-DD	yes / no	no
allowImagePDF	Optional	Allow image-based (scanned) PDF processing	yes / no	yes
returnS3Url	Optional	Return a downloadable S3 URL of the processed statement	yes / no	no
flagTransactions	Optional	Flag suspicious transactions	yes / no	no
returnRecurringTransactions	Optional	Return recurring (e.g., monthly) transactions	yes / no	no
returnAverageMonthlyBalance	Optional	Return average monthly balance across statement period	yes / no	no
returnStatementSummary	Optional	Return a summary section with key insights from the statement	yes / no	no
returnEODBalances	Optional	Return end-of-day balances per statement page	yes / no	no
returnSalaryInfo	Optional	Return salary credits and employer name if found	yes / no	no

Request

The following code shows a standard curl request for the API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/bank_statement_analysis' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--form 'pdf=@"<path_to_pdf_file>"' \
--form 'password=' \
--form 'enableFraudChecks="yes"' \
--form 'extractEntities="yes"' \
--form 'country="ind"' \
--form 'returnTransactions="yes"' \
--form 'transactionThreshold="0"' \
--form 'formatDateYearFirst="no"' \
--form 'allowImagePDF="yes"' \
--form 'returnS3Url="yes"' \
--form 'flagTransactions="yes"' \
--form 'returnRecurringTransactions="yes"' \
--form 'returnAverageMonthlyBalance="yes"' \
--form 'returnStatementSummary="yes"' \
--form 'returnEODBalances="yes"' \
--form 'returnSalaryInfo="yes"'

Success Response

The following is a success response from the API:

{
    "status": "success",
    "statusCode": "<Status_Code_Number>",
    "result": [
      {
       "details": {
                "documentType": "<Document_Type_String>",
                "transactionThreshold": "<Transaction_Threshold_Number>",
                "transactions": [
                    {
                        "date": "<Transaction_Date_in_DD/MM/YYYY_Format>",
                        "description": "<Transaction_Description_String>",
                        "mode": "<Transaction_Mode>",
                        "entityName": "<Entity_Name>",
                        "entityName2": "<Entity_Name_Alternative>",
                        "value": "<Transaction_Value_Number>",
                        "type": "<Transaction_Type>",
                        "isSalary": "<Is_Salary_Boolean>",
                        "balance": "<Balance_After_Transaction_Number>"
                    },
                    {
                        "date": "<Transaction_Date_in_DD/MM/YYYY_Format>",
                        "description": "<Transaction_Description_String>",
                        "mode": "<Transaction_Mode>",
                        "entityName": "<Entity_Name>",
                        "entityName2": "<Entity_Name_Alternative>",
                        "value": "<Transaction_Value_Number>",
                        "type": "<Transaction_Type>",
                        "isSalary": "<Is_Salary_Boolean>",
                        "balance": "<Balance_After_Transaction_Number>"
                    },
                    {
                        "date": "<Transaction_Date_in_DD/MM/YYYY_Format>",
                        "description": "<Transaction_Description_String>",
                        "mode": "<Transaction_Mode>",
                        "entityName": "<Entity_Name>",
                        "entityName2": "<Entity_Name_Alternative>",
                        "value": "<Transaction_Value_Number>",
                        "type": "<Transaction_Type>",
                        "isSalary": "<Is_Salary_Boolean>",
                        "balance": "<Balance_After_Transaction_Number>"
                    },
                    {
                        "date": "<Transaction_Date_in_DD/MM/YYYY_Format>",
                        "description": "<Transaction_Description_String>",
                        "mode": "<Transaction_Mode>",
                        "entityName": "<Entity_Name>",
                        "entityName2": "<Entity_Name_Alternative>",
                        "value": "<Transaction_Value_Number>",
                        "type": "<Transaction_Type>",
                        "isSalary": "<Is_Salary_Boolean>",
                        "balance": "<Balance_After_Transaction_Number>"
                    },
                    {
                        "date": "<Transaction_Date_in_DD/MM/YYYY_Format>",
                        "description": "<Transaction_Description_String>",
                        "mode": "<Transaction_Mode>",
                        "entityName": "<Entity_Name>",
                        "entityName2": "<Entity_Name_Alternative>",
                        "value": "<Transaction_Value_Number>",
                        "type": "<Transaction_Type>",
                        "isSalary": "<Is_Salary_Boolean>",
                        "balance": "<Balance_After_Transaction_Number>"
                    },
                    {
                        "date": "<Transaction_Date_in_DD/MM/YYYY_Format>",
                        "description": "<Transaction_Description_String>",
                        "mode": "<Transaction_Mode>",
                        "entityName": "<Entity_Name>",
                        "entityName2": "<Entity_Name_Alternative>",
                        "value": "<Transaction_Value_Number>",
                        "type": "<Transaction_Type>",
                        "isSalary": "<Is_Salary_Boolean>",
                        "balance": "<Balance_After_Transaction_Number>"
                    }
                ],
                "transactions_count": "<Total_Transactions_Count_Number>",
                "num_pages": "<Number_Of_Pages_In_Statement>",
                "total_credit_transactions_count": "<Total_Credit_Transactions_Count>",
                "total_credit_transactions_value": "<Total_Credit_Transactions_Value_Number>",
                "total_debit_transactions_count": "<Total_Debit_Transactions_Count>",
                "total_debit_transactions_value": "<Total_Debit_Transactions_Value_Number>",
                "summary": {
                    "overall": {
                        "numberOfTransactions": "<Overall_Number_Of_Transactions>",
                        "openingBalance": "<Overall_Opening_Balance_Number>",
                        "closingBalance": "<Overall_Closing_Balance_Number>",
                        "minimumBalance": "<Overall_Minimum_Balance_Number>",
                        "maximumBalance": "<Overall_Maximum_Balance_Number>",
                        "averageBalance": "<Overall_Average_Balance_Number>",
                        "minimumDailyBalance": "<Overall_Minimum_Daily_Balance_Number>",
                        "maximumDailyBalance": "<Overall_Maximum_Daily_Balance_Number>",
                        "averageDailyBalance": "<Overall_Average_Daily_Balance_Number>",
                        "minimumWeeklyBalance": "<Overall_Minimum_Weekly_Balance_Number>",
                        "maximumWeeklyBalance": "<Overall_Maximum_Weekly_Balance_Number>",
                        "averageWeeklyBalance": "<Overall_Average_Weekly_Balance_Number>",
                        "minimumMonthlyBalance": "<Overall_Minimum_Monthly_Balance_Number>",
                        "maximumMonthlyBalance": "<Overall_Maximum_Monthly_Balance_Number>",
                        "averageMonthlyBalance": "<Overall_Average_Monthly_Balance_Number>",
                        "numberOfCreditTransactions": "<Overall_Number_Of_Credit_Transactions>",
                        "totalCreditAmount": "<Overall_Total_Credit_Amount_Number>",
                        "minimumCreditAmount": "<Overall_Minimum_Credit_Amount_Number>",
                        "maximumCreditAmount": "<Overall_Maximum_Credit_Amount_Number>",
                        "averageCreditAmount": "<Overall_Average_Credit_Amount_Number>",
                        "numberOfDebitTransactions": "<Overall_Number_Of_Debit_Transactions>",
                        "totalDebitAmount": "<Overall_Total_Debit_Amount_Number>",
                        "minimumDebitAmount": "<Overall_Minimum_Debit_Amount_Number>",
                        "maximumDebitAmount": "<Overall_Maximum_Debit_Amount_Number>",
                        "averageDebitAmount": "<Overall_Average_Debit_Amount_Number>",
                        "numberOfSalaryTransactions": "<Overall_Number_Of_Salary_Transactions>",
                        "totalSalaryAmount": "<Overall_Total_Salary_Amount_Number>",
                        "averageSalaryAmount": "<Overall_Average_Salary_Amount_Number>",
                        "creditDebitRatio": "<Overall_Credit_Debit_Ratio_Number>"
                    },
                    "monthly": [
                        {
                            "month": "<Month_Number>",
                            "year": "<Year_Number>",
                            "numberOfTransactions": "<Monthly_Number_Of_Transactions>",
                            "openingBalance": "<Monthly_Opening_Balance_Number>",
                            "closingBalance": "<Monthly_Closing_Balance_Number>",
                            "minimumBalance": "<Monthly_Minimum_Balance_Number>",
                            "maximumBalance": "<Monthly_Maximum_Balance_Number>",
                            "averageBalance": "<Monthly_Average_Balance_Number>",
                            "minimumDailyBalance": "<Monthly_Minimum_Daily_Balance_Number>",
                            "maximumDailyBalance": "<Monthly_Maximum_Daily_Balance_Number>",
                            "averageDailyBalance": "<Monthly_Average_Daily_Balance_Number>",
                            "minimumWeeklyBalance": "<Monthly_Minimum_Weekly_Balance_Number>",
                            "maximumWeeklyBalance": "<Monthly_Maximum_Weekly_Balance_Number>",
                            "averageWeeklyBalance": "<Monthly_Average_Weekly_Balance_Number>",
                            "numberOfCreditTransactions": "<Monthly_Number_Of_Credit_Transactions>",
                            "totalCreditAmount": "<Monthly_Total_Credit_Amount_Number>",
                            "minimumCreditAmount": "<Monthly_Minimum_Credit_Amount_Number>",
                            "maximumCreditAmount": "<Monthly_Maximum_Credit_Amount_Number>",
                            "averageCreditAmount": "<Monthly_Average_Credit_Amount_Number>",
                            "numberOfDebitTransactions": "<Monthly_Number_Of_Debit_Transactions>",
                            "totalDebitAmount": "<Monthly_Total_Debit_Amount_Number>",
                            "minimumDebitAmount": "<Monthly_Minimum_Debit_Amount_Number>",
                            "maximumDebitAmount": "<Monthly_Maximum_Debit_Amount_Number>",
                            "averageDebitAmount": "<Monthly_Average_Debit_Amount_Number>",
                            "numberOfSalaryTransactions": "<Monthly_Number_Of_Salary_Transactions>",
                            "totalSalaryAmount": "<Monthly_Total_Salary_Amount_Number>",
                            "averageSalaryAmount": "<Monthly_Average_Salary_Amount_Number>",
                            "eodBalances": "<Array_Of_End_Of_Day_Balance_Numbers>"
                        },
                        {
                            "month": "<Month_Number>",
                            "year": "<Year_Number>",
                            "numberOfTransactions": "<Monthly_Number_Of_Transactions>",
                            "openingBalance": "<Monthly_Opening_Balance_Number>",
                            "closingBalance": "<Monthly_Closing_Balance_Number>",
                            "minimumBalance": "<Monthly_Minimum_Balance_Number>",
                            "maximumBalance": "<Monthly_Maximum_Balance_Number>",
                            "averageBalance": "<Monthly_Average_Balance_Number>",
                            "minimumDailyBalance": "<Monthly_Minimum_Daily_Balance_Number>",
                            "maximumDailyBalance": "<Monthly_Maximum_Daily_Balance_Number>",
                            "averageDailyBalance": "<Monthly_Average_Daily_Balance_Number>",
                            "minimumWeeklyBalance": "<Monthly_Minimum_Weekly_Balance_Number>",
                            "maximumWeeklyBalance": "<Monthly_Maximum_Weekly_Balance_Number>",
                            "averageWeeklyBalance": "<Monthly_Average_Weekly_Balance_Number>",
                            "numberOfCreditTransactions": "<Monthly_Number_Of_Credit_Transactions>",
                            "totalCreditAmount": "<Monthly_Total_Credit_Amount_Number>",
                            "minimumCreditAmount": "<Monthly_Minimum_Credit_Amount_Number>",
                            "maximumCreditAmount": "<Monthly_Maximum_Credit_Amount_Number>",
                            "averageCreditAmount": "<Monthly_Average_Credit_Amount_Number>",
                            "numberOfDebitTransactions": "<Monthly_Number_Of_Debit_Transactions>",
                            "totalDebitAmount": "<Monthly_Total_Debit_Amount_Number>",
                            "minimumDebitAmount": "<Monthly_Minimum_Debit_Amount_Number>",
                            "maximumDebitAmount": "<Monthly_Maximum_Debit_Amount_Number>",
                            "averageDebitAmount": "<Monthly_Average_Debit_Amount_Number>",
                            "numberOfSalaryTransactions": "<Monthly_Number_Of_Salary_Transactions>",
                            "totalSalaryAmount": "<Monthly_Total_Salary_Amount_Number>",
                            "averageSalaryAmount": "<Monthly_Average_Salary_Amount_Number>",
                            "eodBalances": "<Array_Of_End_Of_Day_Balance_Numbers>"
                        }
                    ]
                }
            },
            "fraudChecks": {
                "date": "<Fraud_Check_Date_Status>"
            },
            "s3url": "<S3_Bucket_URL_For_Statement_PDF>"
      }
    ]
}

Success Response Details

Parameter	Type	Description
status	string	Indicates the overall status of the request (success or failure)
statusCode	integer	HTTP status code of the response (e.g., 200 for success)
result	list	List of result objects (generally a single object)
message	string	The error message, only present in the case of an error
result.details.documentType	string	Type of input document analyzed (e.g., TEXT_PDF)
result.details.transactionThreshold	float	Configured threshold value for transaction analysis
result.details.transactions	list	List of individual transaction entries extracted from the document
result.details.transactions_count	integer	Total number of transactions parsed
result.details.num_pages	integer	Number of pages in the analyzed PDF document
result.details.total_credit_transactions_count	integer	Total count of credit transactions
result.details.total_credit_transactions_value	float	Sum of values of all credit transactions
result.details.total_debit_transactions_count	integer	Total count of debit transactions
result.details.total_debit_transactions_value	float	Sum of values of all debit transactions
result.details.transactions[].date	string	Date of the transaction in DD/MM/YYYY format
result.details.transactions[].description	string	Full description of the transaction
result.details.transactions[].mode	string	Mode of the transaction (e.g., UPI, NEFT, IMPS)
result.details.transactions[].entityName	string	Name of the transacting party (extracted from narration)
result.details.transactions[].entityName2	string	Duplicate of entityName (can be used for comparison/sanitization)
result.details.transactions[].value	float	Value of the transaction
result.details.transactions[].type	string	Type of transaction (credit, debit)
result.details.transactions[].isSalary	boolean	Indicates whether the transaction is a salary credit
result.details.transactions[].balance	float	Balance in the account after this transaction
result.details.summary.overall.numberOfTransactions	integer	Total number of transactions in the report
result.details.summary.overall.openingBalance	float	Balance at the beginning of the analysis period
result.details.summary.overall.closingBalance	float	Balance at the end of the analysis period
result.details.summary.overall.minimumBalance	float	Minimum balance during the analysis period
result.details.summary.overall.maximumBalance	float	Maximum balance during the analysis period
result.details.summary.overall.averageBalance	float	Average balance during the period
result.details.summary.overall.minimumDailyBalance	float	Lowest end-of-day balance recorded
result.details.summary.overall.maximumDailyBalance	float	Highest end-of-day balance recorded
result.details.summary.overall.averageDailyBalance	float	Average of all daily balances
result.details.summary.overall.minimumWeeklyBalance	float	Lowest weekly balance
result.details.summary.overall.maximumWeeklyBalance	float	Highest weekly balance
result.details.summary.overall.averageWeeklyBalance	float	Average of weekly balances
result.details.summary.overall.minimumMonthlyBalance	float	Lowest monthly balance
result.details.summary.overall.maximumMonthlyBalance	float	Highest monthly balance
result.details.summary.overall.averageMonthlyBalance	float	Average of monthly balances
result.details.summary.overall.numberOfCreditTransactions	integer	Number of credit transactions
result.details.summary.overall.totalCreditAmount	float	Total credit transaction amount
result.details.summary.overall.minimumCreditAmount	float	Minimum credit amount
result.details.summary.overall.maximumCreditAmount	float	Maximum credit amount
result.details.summary.overall.averageCreditAmount	float	Average credit amount
result.details.summary.overall.numberOfDebitTransactions	integer	Number of debit transactions
result.details.summary.overall.totalDebitAmount	float	Total debit amount
result.details.summary.overall.minimumDebitAmount	float	Minimum debit amount
result.details.summary.overall.maximumDebitAmount	float	Maximum debit amount
result.details.summary.overall.averageDebitAmount	float	Average debit amount
result.details.summary.overall.numberOfSalaryTransactions	integer	Number of salary-related credit transactions
result.details.summary.overall.totalSalaryAmount	float	Total salary amount credited
result.details.summary.overall.averageSalaryAmount	float	Average of salary amounts credited
result.details.summary.overall.creditDebitRatio	float	Ratio of total credit to total debit values
result.details.summary.monthly[].month	integer	Month number (e.g., 1 = Jan, 12 = Dec)
result.details.summary.monthly[].year	integer	Year (e.g., 2023)
result.details.summary.monthly[].numberOfTransactions	integer	Transactions in that month
result.details.summary.monthly[].openingBalance	float	Balance at the start of the month
result.details.summary.monthly[].closingBalance	float	Balance at the end of the month
result.details.summary.monthly[].minimumBalance	float	Lowest balance in the month
result.details.summary.monthly[].maximumBalance	float	Highest balance in the month
result.details.summary.monthly[].averageBalance	float	Average balance for the month
result.details.summary.monthly[].minimumDailyBalance	float	Min EOD (End of Day) balance in the month
result.details.summary.monthly[].maximumDailyBalance	float	Max EOD balance in the month
result.details.summary.monthly[].averageDailyBalance	float	Average of EOD balances
result.details.summary.monthly[].minimumWeeklyBalance	float	Min weekly balance
result.details.summary.monthly[].maximumWeeklyBalance	float	Max weekly balance
result.details.summary.monthly[].averageWeeklyBalance	float	Average weekly balance
result.details.summary.monthly[].numberOfCreditTransactions	integer	Count of credit transactions
result.details.summary.monthly[].totalCreditAmount	float	Total credited amount
result.details.summary.monthly[].minimumCreditAmount	float	Minimum single credit amount
result.details.summary.monthly[].maximumCreditAmount	float	Maximum single credit amount
result.details.summary.monthly[].averageCreditAmount	float	Average of credit transactions
result.details.summary.monthly[].numberOfDebitTransactions	integer	Count of debit transactions
result.details.summary.monthly[].totalDebitAmount	float	Total debited amount
result.details.summary.monthly[].minimumDebitAmount	float	Minimum single debit amount
result.details.summary.monthly[].maximumDebitAmount	float	Maximum single debit amount
result.details.summary.monthly[].averageDebitAmount	float	Average of debit transactions
result.details.summary.monthly[].numberOfSalaryTransactions	integer	Number of salary entries
result.details.summary.monthly[].totalSalaryAmount	float	Total salary received in that month
result.details.summary.monthly[].averageSalaryAmount	float	Average salary received in that month
result.details.summary.monthly[].eodBalances	list[float]	End-of-day balances for each day of the month
result.fraudChecks.date	string	Fraud check status related to date parsing (e.g., passed)
result.s3url	string	Pre-signed AWS S3 URL to download the input PDF file used

Error Responses

The following are some sample error responses from the API.

Required PDF parameter missing

{
  "message": "Input Validation Error: requires property \"uploadPdf\"",
  "statusCode": 400,
  "status": "failure"
}

Invalid File Type - PDF

{
  "message": "Invalid file type for: uploadPdf",
  "statusCode": 400,
  "status": "failure"
}

Incorrect Password Provided for PDF

{
    "message": "Password provided was incorrect",
    "statusCode": 400,
    "status": "failure"
}

Internal Server Error

{
  "status": "failure",
  "statusCode": 500,
  "message": "internal server error"
}

Error Response Details

A failure or error response from the module contains a failure status, with a relavant status code and error message.

The following table lists all error responses:

Status Code	Error Message	Error Description
400	Input Validation Error: requires property "uploadPdf"	The required parameter "uploadPdf" is missing from the request.
400	Invalid file type for: uploadPdf	The file type provided for the "uploadPdf" parameter is invalid. Please ensure the file is in PDF format.
400	Password provided was incorrect	The password provided for the PDF file is incorrect. Please check and try again.
500	Internal Server Error	An internal server error occurred. Please check the request or contact support for assistance.