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 requested documentId or applicationId does 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."
}