Kaaj Bank Statement Analysis API

This document describes the API endpoint for processing and analyzing bank statements. The endpoint accepts a list of PDF files (each with an associated appId) and returns an Excel file containing enriched transactions along with various analytical reports.

---

Endpoint

POST https://api.kaaj.ai/application/bankstatement-analysis

---

Headers

Authorization: Bearer <your_api_key> Content-Type: multipart/form-data

---

Request Body

The request is submitted as multipart/form-data and must include:

1. PDF Files: One or more bank statement PDF files.
2. JSON Metadata: A JSON field named metadata containing an array of objects. Each object must include:
   • appId (string, required): Unique identifier for the application/form associated with the PDF file.
   • fileName (string, required): Name of the corresponding PDF file.

Example Metadata (as a JSON field)

{
  "files": [
    {
      "appId": "APP001",
      "fileName": "statement_january.pdf"
    },
    {
      "appId": "APP002",
      "fileName": "statement_february.pdf"
    }
  ]
}

Raw Transactions Table

Out AI models extract all transactions and understand the context behind every transaction. We then categorize the transactions into detailed subcategories and their accounting categories. The table contains the following columns:

Column Name	Description
date	The date of the transaction
description	A description of the transaction
amount	The monetary amount of the transaction (positive or negative)
direction	Indicates the transaction type (e.g., debit or credit)
accounting_category	The primary accounting category for the transaction
subcategory_name	The subcategory name within the accounting category
merchant_name	The name of the merchant or entity involved in the transaction

Analysis Reports

The API performs multiple analyses on the transactions. The enriched analysis includes the following categories:

• Loans Analysis: Detailed analysis of loan-related transactions.
• NSF Fees: Identification of new non-sufficient funds (NSF) transactions.
• Loan Payments: Transactions related to loan payments.
• Financing Transactions: Analysis of financing-related transactions.
• Revenue: Summaries of revenue-generating transactions.
• Revenue Credit: Analysis of credits that contribute to revenue.
• Non Revenue Credit: Analysis of credits that do not contribute to revenue.
• Loan Disbursements: Details of loan disbursement transactions.
• Probable Recurring: Identification of probable recurring transactions.
• Interbank: Analysis of interbank transactions.
• Operational Expenses: Breakdown of operational expenses.

Response

The API returns an Excel file (.xlsx) containing multiple sheets:

• Enriched Transactions: A sheet with the raw transactions table augmented with analysis fields.
• Analytical Reports: Additional sheets for each analysis category:
  • Loans Analysis
  • NSF Fees
  • Loan Payments
  • Financing Transactions
  • Revenue
  • Revenue Credit
  • Non-Revenue Credit
  • Loan Disbursements
  • Probable Recurring
  • Interbank
  • Operational Expenses

Success Response

Code: 200 OK Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Error Response

Code: 400 Bad Request

{
  "message": "Missing required fields: ensure all PDF files and corresponding metadata (appId and fileName) are provided."
}

Additional Notes

• File Upload Limitations: Each PDF file must adhere to the maximum file size limit (25MB).
• Processing Time: Processing may take several minutes depending on the number and size of the PDFs.
• Logging: All requests are logged, including the file metadata, for auditing and troubleshooting purposes.
• Download URL Validity: The provided download URL for the Excel file is valid for 24 hours.