Document Management API
The Document Management API provides a robust set of endpoints for uploading loan-related documents and performing AI-powered analysis on them. These endpoints handle secure storage, metadata tracking, and the extraction of financial insights from bank statements, tax returns, and financial reports.
Authentication
All API endpoints require an active session. Requests must be made from a front-end context where the Supabase auth cookie is present or by providing appropriate authorization headers. If a session is missing or invalid, the API returns a 401 Unauthorized response.
Document Upload
Handles the secure upload of files to the configured storage provider (local or cloud) and registers the document in the database.
POST /api/documents/upload
Uploads a file and associates it with a specific loan application.
Request Type: multipart/form-data
Body Parameters:
| Field | Type | Description |
| :--- | :--- | :--- |
| file | File | The document (PDF, PNG, JPG) to upload. |
| applicationId | string | The UUID of the loan application. |
| organizationId | string | The UUID of the organization. |
| documentType | string | The category (e.g., bank_statement, gst_return, id_proof). |
Success Response: 200 OK
{
"success": true,
"documentId": "uuid-of-document",
"filePath": "org-id/app-id/timestamp_filename.pdf"
}
AI Document Analysis
These endpoints process previously uploaded documents using AI to extract structured data.
POST /api/analyze/bank-statement
Analyzes a bank statement to extract transaction history, balances, and fraud risk metrics.
Request Body:
{
"documentId": "string",
"applicationId": "string",
"organizationId": "string",
"aiProvider": "openai" // Optional: "openai" | "anthropic" | "gemini"
}
Key Extracted Data:
- Summary: Average balance, net income, total credits/debits.
- Fraud Risk: Overall risk score, cash deposit percentages, and fraud flags.
- Repayment Capacity: Detected EMIs and debt-to-inflow ratios.
POST /api/analyze/financial-statement
Extracts data from Balance Sheets, Profit & Loss statements, or Income Tax Returns (ITR).
Request Body:
{
"documentId": "string",
"applicationId": "string",
"organizationId": "string",
"statementType": "balance_sheet", // "balance_sheet" | "profit_loss" | "itr"
"aiProvider": "openai"
}
GST Returns API
Manages the extraction and retrieval of GST-related financial data.
GET /api/analyze/gst-returns
Fetches all existing GST analyses for a specific application.
Query Parameters:
applicationId: The UUID of the application.
POST /api/analyze/gst-returns
Processes a GST document. This endpoint supports both JSON payloads (referencing an existing documentId) and direct multipart/form-data uploads.
Request Body (JSON):
{
"applicationId": "string",
"documentId": "string"
}
Reconciliation & Synthesis
These endpoints aggregate data across multiple document types to provide a holistic view of the borrower's profile.
POST /api/analyze/reconciliation
Cross-references data between Bank Statements, GST Returns, and P&L Statements to identify discrepancies.
Request Body:
{
"applicationId": "string"
}
Output: A comparison of revenue/turnover reported across different sources (e.g., Bank Inflows vs. GST Sales vs. P&L Revenue).
POST /api/analyze/credit-memo
Generates a comprehensive Credit Memo by synthesizing the borrower's application data, bank analysis, and financial ratios.
Request Body:
{
"applicationId": "string",
"organizationId": "string",
"aiProvider": "openai"
}
Error Handling
The API uses standard HTTP status codes:
400 Bad Request: Missing required fields or invalid file types.401 Unauthorized: Authentication failed or session expired.404 Not Found: The requesteddocumentIdorapplicationIddoes not exist.500 Internal Server Error: AI processing failure or database connection issues.
Example Error Response:
{
"error": "Document not found",
"details": "The provided documentId does not exist in the database."
}