Financial Analytics Module - API Documentation

This document provides detailed information about the RESTful API endpoints available in the Financial Analytics Module.

API Conventions

Base URL

All API endpoints are relative to the base URL:

https://your-domain.com/api/

Authentication

All API requests require authentication using JWT (JSON Web Token). Include the token in the Authorization header:

Authorization: Bearer <your_jwt_token>

Response Format

All responses are in JSON format. Successful responses include a success field set to true and, depending on the endpoint, a data field containing the requested information:

{
  "success": true,
  "data": { ... }
}

Error responses include a success field set to false, an error field describing the error, and optionally a details field:

{
  "success": false,
  "error": "Description of the error",
  "details": { ... }
}

HTTP Status Codes

The API uses standard HTTP status codes:

200 OK - The request succeeded
201 Created - Resource created successfully
400 Bad Request - Invalid request parameters
401 Unauthorized - Authentication required or failed
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
422 Unprocessable Entity - Validation errors
500 Internal Server Error - Server-side error

Document Management Endpoints

Upload Document

Uploads a new financial document for processing.

URL: POST /documents

Content-Type: multipart/form-data

Request Parameters:

Parameter	Type	Required	Description
file	File	Yes	The document file (PDF, CSV, XLSX)
document_type	String	No	Type of document (bank_statement, invoice, receipt)
description	String	No	Document description
date	String	No	Document date (YYYY-MM-DD)
source	String	No	Document source (bank name, vendor)

Response:

{
  "success": true,
  "data": {
    "document_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "upload_date": "2023-05-15T10:30:45Z"
  }
}

List Documents

Retrieves a list of uploaded documents.

URL: GET /documents

Query Parameters:

Parameter	Type	Required	Description
page	Integer	No	Page number (default: 1)
per_page	Integer	No	Items per page (default: 20, max: 100)
status	String	No	Filter by status (pending, processing, completed, failed)
start_date	String	No	Filter by upload date range start (YYYY-MM-DD)
end_date	String	No	Filter by upload date range end (YYYY-MM-DD)
document_type	String	No	Filter by document type

Response:

{
  "success": true,
  "data": {
    "documents": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "file_name": "bank_statement_may_2023.pdf",
        "document_type": "bank_statement",
        "status": "completed",
        "upload_date": "2023-05-15T10:30:45Z",
        "processing_date": "2023-05-15T10:32:10Z",
        "source": "Chase Bank",
        "page_count": 4,
        "transaction_count": 32
      },
      // ... more documents
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_items": 98,
      "per_page": 20
    }
  }
}

Get Document Details

Retrieves details for a specific document.

URL: GET /documents/{document_id}

Path Parameters:

Parameter	Type	Required	Description
document_id	UUID	Yes	Document ID

Response:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "file_name": "bank_statement_may_2023.pdf",
    "document_type": "bank_statement",
    "description": "May 2023 Chase Bank Statement",
    "status": "completed",
    "upload_date": "2023-05-15T10:30:45Z",
    "processing_date": "2023-05-15T10:32:10Z",
    "source": "Chase Bank",
    "page_count": 4,
    "file_size": 1258423,
    "mime_type": "application/pdf",
    "transaction_count": 32,
    "date_range": {
      "start_date": "2023-05-01",
      "end_date": "2023-05-31"
    }
  }
}

Delete Document

Deletes a document and its associated data.

URL: DELETE /documents/{document_id}

Path Parameters:

Parameter	Type	Required	Description
document_id	UUID	Yes	Document ID

Response:

{
  "success": true,
  "data": {
    "message": "Document deleted successfully"
  }
}

Transaction Endpoints

List Transactions

Retrieves a list of transactions, optionally filtered by document or other criteria.

URL: GET /transactions

Query Parameters:

Parameter	Type	Required	Description
page	Integer	No	Page number (default: 1)
per_page	Integer	No	Items per page (default: 50, max: 200)
document_id	UUID	No	Filter by document ID
start_date	String	No	Filter by transaction date range start (YYYY-MM-DD)
end_date	String	No	Filter by transaction date range end (YYYY-MM-DD)
category_id	UUID	No	Filter by category ID
min_amount	Number	No	Filter by minimum amount
max_amount	Number	No	Filter by maximum amount
merchant	String	No	Filter by merchant name (partial match)
type	String	No	Filter by transaction type (credit, debit)
search	String	No	Search in description and merchant fields

Response:

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440011",
        "document_id": "550e8400-e29b-41d4-a716-446655440000",
        "date": "2023-05-10",
        "description": "Payment to ACME Corp",
        "amount": -125.50,
        "merchant": "ACME Corporation",
        "category_id": "550e8400-e29b-41d4-a716-446655440022",
        "category_name": "Utilities",
        "account": "Checking Account ****1234",
        "type": "debit",
        "is_recurring": true
      },
      // ... more transactions
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 12,
      "total_items": 583,
      "per_page": 50
    },
    "summary": {
      "total_credits": 6250.75,
      "total_debits": -4328.92,
      "net_amount": 1921.83
    }
  }
}

Update Transaction Category

Updates the category of a transaction.

URL: PATCH /transactions/{transaction_id}/category

Path Parameters:

Parameter	Type	Required	Description
transaction_id	UUID	Yes	Transaction ID

Request Body:

{
  "category_id": "550e8400-e29b-41d4-a716-446655440033",
  "apply_to_similar": false
}

Request Parameters:

Parameter	Type	Required	Description
category_id	UUID	Yes	Category ID to assign
apply_to_similar	Boolean	No	Apply this category to similar transactions (default: false)

Response:

{
  "success": true,
  "data": {
    "transaction_id": "550e8400-e29b-41d4-a716-446655440011",
    "category_id": "550e8400-e29b-41d4-a716-446655440033",
    "category_name": "Groceries",
    "similar_updated_count": 0
  }
}

Category Management Endpoints

Retrieves the list of transaction categories.

URL: GET /categories

Query Parameters:

Parameter	Type	Required	Description
include_system	Boolean	No	Include system categories (default: true)
include_custom	Boolean	No	Include custom categories (default: true)
parent_id	UUID	No	Filter by parent category ID

Response:

{
  "success": true,
  "data": {
    "categories": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440022",
        "name": "Utilities",
        "type": "expense",
        "color": "#3498db",
        "parent_id": null,
        "is_system": true,
        "subcategories": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440023",
            "name": "Electricity",
            "type": "expense",
            "color": "#2980b9",
            "parent_id": "550e8400-e29b-41d4-a716-446655440022",
            "is_system": true
          },
          // ... more subcategories
        ]
      },
      // ... more categories
    ]
  }
}

Create Category

Creates a new custom category.

URL: POST /categories

Request Body:

{
  "name": "Home Improvement",
  "type": "expense",
  "color": "#8e44ad",
  "parent_id": null
}

Request Parameters:

Parameter	Type	Required	Description
name	String	Yes	Category name
type	String	Yes	Category type (income, expense, transfer)
color	String	No	Color hex code
parent_id	UUID	No	Parent category ID for hierarchical categories

Response:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440044",
    "name": "Home Improvement",
    "type": "expense",
    "color": "#8e44ad",
    "parent_id": null,
    "is_system": false
  }
}

Analytics Endpoints

Transaction Summary

Returns a summary of transactions by category.

URL: GET /analytics/transaction-summary

Query Parameters:

Parameter	Type	Required	Description
start_date	String	Yes	Summary period start date (YYYY-MM-DD)
end_date	String	Yes	Summary period end date (YYYY-MM-DD)
group_by	String	No	Grouping (category, merchant, day, week, month) (default: category)
previous_period	Boolean	No	Include previous period comparison (default: false)

Response:

{
  "success": true,
  "data": {
    "summary": {
      "total_income": 5250.75,
      "total_expenses": 3328.92,
      "net_amount": 1921.83,
      "period": "May 2023"
    },
    "categories": [
      {
        "category_id": "550e8400-e29b-41d4-a716-446655440022",
        "category_name": "Utilities",
        "total_amount": 312.45,
        "count": 4,
        "percentage": 9.4,
        "previous_period_amount": 298.32,
        "change_percentage": 4.7
      },
      // ... more categories
    ]
  }
}

Cash Flow Predictions

Returns cash flow predictions for future periods.

URL: GET /analytics/cash-flow/predictions

Query Parameters:

Parameter	Type	Required	Description
start_date	String	No	Prediction start date (YYYY-MM-DD)
end_date	String	No	Prediction end date (YYYY-MM-DD)
period	String	No	Prediction period (day, week, month) (default: day)

Response:

{
  "success": true,
  "data": {
    "predictions": [
      {
        "date": "2023-06-01",
        "predicted_inflow": 0.00,
        "predicted_outflow": 45.67,
        "net_cash_flow": -45.67,
        "balance": 1876.16,
        "confidence": 0.85
      },
      {
        "date": "2023-06-02",
        "predicted_inflow": 2500.00,
        "predicted_outflow": 150.00,
        "net_cash_flow": 2350.00,
        "balance": 4226.16,
        "confidence": 0.92
      },
      // ... more days
    ],
    "summary": {
      "total_predicted_inflow": 5250.00,
      "total_predicted_outflow": 3425.75,
      "net_cash_flow": 1824.25,
      "start_balance": 1921.83,
      "end_balance": 3746.08
    }
  }
}

Budget Progress

Returns the progress of budgets for the current period.

URL: GET /analytics/budgets/progress

Query Parameters:

Parameter	Type	Required	Description
budget_id	UUID	No	Filter by specific budget ID
period	String	No	Specific period (current, previous, YYYY-MM)

Response:

{
  "success": true,
  "data": {
    "budgets": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440055",
        "name": "Monthly Budget",
        "period": "May 2023",
        "total_allocated": 3500.00,
        "total_spent": 2845.67,
        "percentage_used": 81.3,
        "days_remaining": 5,
        "status": "on_track",
        "categories": [
          {
            "category_id": "550e8400-e29b-41d4-a716-446655440022",
            "category_name": "Utilities",
            "allocated": 350.00,
            "spent": 312.45,
            "percentage_used": 89.3,
            "status": "on_track"
          },
          // ... more categories
        ]
      }
    ]
  }
}

Financial Goals Status

Returns the status of financial goals.

URL: GET /analytics/goals/status

Query Parameters:

Parameter	Type	Required	Description
goal_id	UUID	No	Filter by specific goal ID
status	String	No	Filter by goal status (in_progress, achieved, behind_schedule)

Response:

{
  "success": true,
  "data": {
    "goals": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440066",
        "name": "Emergency Fund",
        "type": "saving",
        "target_amount": 10000.00,
        "current_amount": 6500.00,
        "start_date": "2023-01-01",
        "target_date": "2023-12-31",
        "percentage_complete": 65.0,
        "time_percentage_elapsed": 41.7,
        "status": "ahead_of_schedule",
        "projected_completion_date": "2023-10-15"
      },
      // ... more goals
    ]
  }
}

Financial Planning Endpoints

Create Financial Scenario

Creates a new financial planning scenario.

URL: POST /planning/scenarios

Request Body:

{
  "name": "Promotion Scenario",
  "description": "Financial projection with expected promotion",
  "start_date": "2023-06-01",
  "end_date": "2024-05-31",
  "items": [
    {
      "name": "Current Salary",
      "type": "income",
      "amount": 5000,
      "frequency": "monthly",
      "start_date": "2023-06-01",
      "end_date": "2023-08-31",
      "growth_rate": 0
    },
    {
      "name": "Salary After Promotion",
      "type": "income",
      "amount": 6500,
      "frequency": "monthly",
      "start_date": "2023-09-01",
      "end_date": "2024-05-31",
      "growth_rate": 0.03
    },
    {
      "name": "Rent",
      "type": "expense",
      "amount": 1600,
      "frequency": "monthly",
      "start_date": "2023-06-01",
      "end_date": "2024-05-31",
      "growth_rate": 0
    }
    // ... more scenario items
  ]
}

Response:

{
  "success": true,
  "data": {
    "scenario_id": "550e8400-e29b-41d4-a716-446655440077",
    "name": "Promotion Scenario",
    "item_count": 3,
    "created_at": "2023-05-15T14:30:45Z"
  }
}

Get Scenario Projections

Retrieves financial projections for a scenario.

URL: GET /planning/scenarios/{scenario_id}/projections

Path Parameters:

Parameter	Type	Required	Description
scenario_id	UUID	Yes	Scenario ID

Response:

{
  "success": true,
  "data": {
    "scenario": {
      "id": "550e8400-e29b-41d4-a716-446655440077",
      "name": "Promotion Scenario",
      "description": "Financial projection with expected promotion",
      "start_date": "2023-06-01",
      "end_date": "2024-05-31"
    },
    "summary": {
      "total_annual_income": 71500.00,
      "total_annual_expenses": 19200.00,
      "annual_net_cash_flow": 52300.00,
      "average_monthly_cash_flow": 4358.33,
      "savings_rate": 73.1
    },
    "monthly_projections": [
      {
        "period": "2023-06",
        "total_income": 5000.00,
        "total_expenses": 1600.00,
        "net_cash_flow": 3400.00,
        "running_balance": 3400.00
      },
      // ... more months
    ],
    "visualization_data": {
      // Chart data for frontend visualization
    }
  }
}

Error Codes and Messages

Code	Message	Description
AUTH_001	Authentication required	No authentication token provided
AUTH_002	Invalid token	The authentication token is invalid or expired
DOC_001	Invalid document format	The uploaded file format is not supported
DOC_002	Document not found	The requested document does not exist
TRANS_001	Transaction not found	The requested transaction does not exist
CAT_001	Category not found	The requested category does not exist
API_001	Invalid request parameters	The request contains invalid parameters
API_002	Missing required parameter	A required parameter is missing
SRV_001	Internal server error	An unexpected error occurred on the server

Financial Analytics Module - API Documentation

API Conventions

Base URL

Authentication

Response Format

HTTP Status Codes

Document Management Endpoints

Upload Document

List Documents

Get Document Details

Delete Document

Transaction Endpoints

List Transactions

Update Transaction Category

Category Management Endpoints

List Categories

Create Category

Analytics Endpoints

Transaction Summary

Cash Flow Predictions

Budget Progress

Financial Goals Status

Financial Planning Endpoints

Create Financial Scenario

Get Scenario Projections

Error Codes and Messages