InfraNotes Module · v0.37.15
Welcome
Select a document from the sidebar to read it.
Financial Analytics Module - API Reference
Overview
This document provides a comprehensive reference for all Financial Analytics Module API endpoints. All endpoints require JWT authentication via Bearer token unless otherwise specified.
Base URL: https://api.yourdomain.com
Authentication: Authorization: Bearer <jwt_token>
Health & Status
Health Check
- Method:
GET - Endpoint:
/api/health - Authentication: Not required
- Description: Check API health status
- Response:
{"status": "healthy", "timestamp": "2024-01-15T10:30:00Z"}
Version Info
- Method:
GET - Endpoint:
/version - Authentication: Not required
- Description: Get API version information
- Response:
{"version": "0.4.0", "build": "prod"}
Document Management
Upload Financial Document
- Method:
POST - Endpoint:
/api/documents - Content-Type:
multipart/form-data - Description: Upload and process financial documents (bank statements, CSV files)
- Request Parameters:
file: File object (required)dataSource: String - "personal_banking", "business_banking", "credit_card", "investment" (required)
- Response: Document object with processing status
List Documents
- Method:
GET - Endpoint:
/api/documents - Description: List user's uploaded documents with optional filters
- Query Parameters:
limit: Number (default: 20)offset: Number (default: 0)status: String - "pending", "processing", "completed", "failed"dataSource: String - filter by data source
- Response: Array of document objects with pagination
Get Document Details
- Method:
GET - Endpoint:
/api/documents/{id} - Description: Get details of a specific document
- Response: Single document object
Get Document Transactions
- Method:
GET - Endpoint:
/api/documents/{id}/transactions - Description: Get all transactions extracted from a document
- Response: Array of transaction objects
Process Document
- Method:
POST - Endpoint:
/api/documents/{id}/process - Description: Manually trigger document processing
- Response: Processing status confirmation
Delete Document
- Method:
DELETE - Endpoint:
/api/documents/{id} - Description: Delete a document and its associated data
- Response:
204 No Content
Transaction Analytics
Get Analytics Summary
- Method:
GET - Endpoint:
/api/analytics/summary - Description: Get financial analytics summary for a specific period
- Query Parameters:
startDate: ISO date stringendDate: ISO date stringperiod: "weekly", "monthly", "quarterly", "yearly"
- Response: Summary object with income, expenses, trends, and top categories
Get Summary Comparison
- Method:
GET - Endpoint:
/api/analytics/summary/compare - Description: Compare financial summaries between two periods
- Query Parameters:
currentPeriod: String (e.g., "2024-01")previousPeriod: String (e.g., "2023-12")
- Response: Comparison object with differences and percentage changes
Get Top Categories
- Method:
GET - Endpoint:
/api/analytics/summary/categories - Description: Get top spending categories by amount
- Query Parameters:
limit: Number (default: 10)period: String
- Response: Array of category spending summaries
Get Top Merchants
- Method:
GET - Endpoint:
/api/analytics/summary/merchants - Description: Get top merchants by spending amount
- Query Parameters:
limit: Number (default: 10)period: String
- Response: Array of merchant spending summaries
Get Trends Analysis
- Method:
GET - Endpoint:
/api/analytics/trends - Description: Get spending trends analysis
- Query Parameters:
trendType: "increasing", "decreasing", "spike", "dip"entityType: "category", "merchant", "overall"startDate: ISO date stringendDate: ISO date stringminSignificance: Number (0-1)limit: Number
- Response: Array of trend objects with significance scores
Get Significant Trends
- Method:
GET - Endpoint:
/api/analytics/trends/significant - Description: Get most significant spending trends
- Query Parameters:
limit: Number (default: 5)
- Response: Array of most significant trends
Get Recurring Transactions
- Method:
GET - Endpoint:
/api/analytics/recurring - Description: Get detected recurring transactions
- Query Parameters:
confidence: Number (0-1, default: 0.8)limit: Number (default: 20)
- Response: Array of recurring transaction patterns
Get Upcoming Recurring Transactions
- Method:
GET - Endpoint:
/api/analytics/recurring/upcoming - Description: Get upcoming recurring transactions
- Query Parameters:
days: Number (default: 30)
- Response: Array of predicted upcoming transactions
Refresh Analytics
- Method:
POST - Endpoint:
/api/analytics/refresh - Description: Manually trigger analytics refresh
- Response: Refresh status confirmation
Budget Management
Create Budget
- Method:
POST - Endpoint:
/api/planning/budgets - Description: Create a new budget with category allocations
- Request Payload:
{
"name": "Monthly Household Budget",
"description": "Family budget for monthly expenses",
"totalAmount": "4500.00",
"period": "monthly",
"startDate": "2024-01-01T00:00:00Z",
"endDate": "2024-12-31T23:59:59Z",
"isActive": true,
"autoRenew": true,
"notifyThreshold": 80,
"includeRecurring": true,
"categories": [
{
"categoryId": "uuid",
"categoryName": "Groceries",
"amount": "600.00"
}
]
}
- Response: Created budget object
List Budgets
- Method:
GET - Endpoint:
/api/planning/budgets - Description: List user's budgets with optional filters
- Query Parameters:
name: String - filter by budget nameperiod: String - filter by budget periodisActive: Boolean - filter by active statusstartDateFrom: ISO date stringstartDateTo: ISO date stringincludeInactive: Booleanlimit: Numberoffset: Number
- Response: Array of budget objects with pagination
Get Active Budgets
- Method:
GET - Endpoint:
/api/planning/budgets/active - Description: Get all currently active budgets
- Response: Array of active budget objects
Get Budget Details
- Method:
GET - Endpoint:
/api/planning/budgets/{id} - Description: Get details of a specific budget
- Response: Single budget object
Update Budget
- Method:
PUT - Endpoint:
/api/planning/budgets/{id} - Description: Update an existing budget
- Request Payload: Same structure as Create Budget (excluding categories)
- Response: Updated budget object
Get Budget Progress
- Method:
GET - Endpoint:
/api/planning/budgets/{id}/progress - Description: Get current progress and spending for a budget
- Response: Progress object with spending breakdown by category
Update Budget Progress
- Method:
POST - Endpoint:
/api/planning/budgets/{id}/progress/update - Description: Manually update budget progress (triggers recalculation)
- Response: Updated progress confirmation
Add Budget Category
- Method:
POST - Endpoint:
/api/planning/budgets/{id}/categories - Description: Add a category allocation to a budget
- Request Payload:
{
"categoryId": "uuid",
"categoryName": "Transportation",
"amount": "450.00"
}
- Response: Created category allocation
Get Budget Categories
- Method:
GET - Endpoint:
/api/planning/budgets/{id}/categories - Description: Get all category allocations for a budget
- Response: Array of category allocation objects
Delete Budget
- Method:
DELETE - Endpoint:
/api/planning/budgets/{id} - Description: Delete a budget
- Response:
204 No Content
Financial Goals
Create Financial Goal
- Method:
POST - Endpoint:
/api/v1/goals - Description: Create a new financial goal
- Request Payload:
{
"name": "Emergency Fund",
"description": "Build emergency fund for 6 months of expenses",
"goalType": "emergency_fund",
"targetAmount": "25000.00",
"startDate": "2024-01-01T00:00:00Z",
"targetDate": "2024-12-31T23:59:59Z",
"priority": "high",
"categoryId": "uuid",
"isPublic": false,
"isRecurring": false,
"recurrencePattern": ""
}
- Response: Created goal object
List Goals
- Method:
GET - Endpoint:
/api/v1/goals - Description: List user's financial goals with optional filters
- Query Parameters:
status: "active", "achieved", "cancelled", "on_hold"goalType: String - goal type filterpriority: "low", "medium", "high"limit: Numberoffset: Number
- Response: Array of goal objects with pagination
Get Active Goals
- Method:
GET - Endpoint:
/api/v1/goals/active - Description: Get all active financial goals
- Response: Array of active goal objects
Get Goal Details
- Method:
GET - Endpoint:
/api/v1/goals/{id} - Description: Get details of a specific financial goal
- Response: Single goal object
Update Goal
- Method:
PUT - Endpoint:
/api/v1/goals/{id} - Description: Update an existing financial goal
- Request Payload: Same structure as Create Goal
- Response: Updated goal object
Update Goal Progress
- Method:
PATCH - Endpoint:
/api/v1/goals/{id}/progress - Description: Update the current amount/progress of a goal
- Request Payload:
{
"amount": "8500.00"
}
- Response: Updated goal object
Update Goal Status
- Method:
PATCH - Endpoint:
/api/v1/goals/{id}/status - Description: Update the status of a financial goal
- Request Payload:
{
"status": "achieved"
}
- Response: Updated goal object
Create Goal Contribution
- Method:
POST - Endpoint:
/api/v1/goals/{id}/contributions - Description: Add a contribution to a financial goal
- Request Payload:
{
"amount": "500.00",
"contributionDate": "2024-01-15T00:00:00Z",
"transactionId": "uuid",
"description": "Monthly emergency fund contribution"
}
- Response: Created contribution object
Get Goal Contributions
- Method:
GET - Endpoint:
/api/v1/goals/{id}/contributions - Description: Get all contributions for a goal
- Query Parameters:
limit: Numberoffset: Number
- Response: Array of contribution objects with pagination
Get Goal Analysis - Progress
- Method:
GET - Endpoint:
/api/v1/goals/{id}/analysis/progress - Description: Get progress analysis and projections for a goal
- Response: Analysis object with projections and recommendations
Get Projected Completion Date
- Method:
GET - Endpoint:
/api/v1/goals/{id}/analysis/projected-completion - Description: Get projected completion date for a goal
- Response: Projection object with completion date and confidence
Get Required Monthly Contribution
- Method:
GET - Endpoint:
/api/v1/goals/{id}/analysis/required-contribution - Description: Calculate required monthly contribution to meet goal
- Response: Contribution calculation object
Delete Goal
- Method:
DELETE - Endpoint:
/api/v1/goals/{id} - Description: Delete a financial goal
- Response:
204 No Content
Cash Flow Management
Get Cash Flow Predictions
- Method:
GET - Endpoint:
/api/cashflow/predictions - Description: Get cash flow predictions for future periods
- Query Parameters:
periodType: "weekly", "monthly", "quarterly"startDate: ISO date stringendDate: ISO date stringlimit: Number
- Response: Array of prediction objects with confidence scores
Generate Predictions
- Method:
POST - Endpoint:
/api/cashflow/predictions/generate - Description: Manually trigger cash flow prediction generation
- Response: Generation status confirmation
Get Cash Flow Alerts
- Method:
GET - Endpoint:
/api/cashflow/alerts - Description: Get cash flow alerts with optional filters
- Query Parameters:
status: "pending", "acknowledged", "resolved", "dismissed"severity: "low", "medium", "high"alertType: "low_balance", "negative_flow", "unusual_spending"
- Response: Array of alert objects
Get Active Alerts
- Method:
GET - Endpoint:
/api/cashflow/alerts - Description: Get all active cash flow alerts
- Response: Array of active alert objects
Acknowledge Alert
- Method:
POST - Endpoint:
/api/cashflow/alerts/{id}/acknowledge - Description: Acknowledge a cash flow alert
- Response: Updated alert status
Resolve Alert
- Method:
POST - Endpoint:
/api/cashflow/alerts/{id}/resolve - Description: Mark a cash flow alert as resolved
- Response: Updated alert status
Get Latest Cash Flow Snapshot
- Method:
GET - Endpoint:
/api/cashflow/snapshot/latest - Description: Get the latest cash flow snapshot
- Response: Snapshot object with current and projected balances
Generate Cash Flow Snapshot
- Method:
POST - Endpoint:
/api/cashflow/snapshot/generate - Description: Generate a new cash flow snapshot
- Response: Generated snapshot object
Get Upcoming Recurring Transactions
- Method:
GET - Endpoint:
/api/cashflow/recurring/upcoming - Description: Get upcoming recurring transactions
- Query Parameters:
days: Number (default: 30)limit: Number
- Response: Array of upcoming transaction objects
Detect Recurring Transactions
- Method:
POST - Endpoint:
/api/cashflow/recurring/detect - Description: Manually trigger recurring transaction detection
- Response: Detection status confirmation
Financial Planning
Create Planned Expense
- Method:
POST - Endpoint:
/api/planning/expenses - Description: Create a new planned expense
- Request Payload:
{
"title": "Annual Car Insurance",
"description": "Yearly car insurance premium payment",
"amount": "1200.00",
"dueDate": "2024-03-15T00:00:00Z",
"categoryId": "uuid",
"isRecurring": true,
"recurrenceRule": "FREQ=YEARLY;INTERVAL=1",
"notifyDaysBefore": 30
}
- Response: Created expense object
List Planned Expenses
- Method:
GET - Endpoint:
/api/planning/expenses - Description: List planned expenses with optional filters
- Query Parameters:
limit: Numberoffset: NumberisPaid: BooleancategoryId: UUID
- Response: Array of expense objects with pagination
Get Upcoming Expenses
- Method:
GET - Endpoint:
/api/planning/expenses/upcoming - Description: Get expenses due in the next N days
- Query Parameters:
days: Number (default: 30)categoryId: UUID
- Response: Array of upcoming expense objects
Get Overdue Expenses
- Method:
GET - Endpoint:
/api/planning/expenses/overdue - Description: Get overdue expenses
- Response: Array of overdue expense objects
Get Recurring Expenses
- Method:
GET - Endpoint:
/api/planning/expenses/recurring - Description: Get all recurring expenses
- Response: Array of recurring expense objects
Mark Expense as Paid
- Method:
POST - Endpoint:
/api/planning/expenses/{id}/paid - Description: Mark a planned expense as paid
- Request Payload:
{
"paidDate": "2024-01-15T00:00:00Z",
"actualAmount": "1150.00",
"transactionId": "uuid"
}
- Response: Updated expense object
Get Expense Statistics
- Method:
GET - Endpoint:
/api/planning/expenses/statistics - Description: Get expense statistics and summaries
- Response: Statistics object with totals and breakdowns
Validate Recurrence Rule
- Method:
POST - Endpoint:
/api/planning/recurrence/rule/validate - Description: Validate a recurrence rule
- Request Payload:
{
"rule": "FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=15"
}
- Response: Validation result object
Describe Recurrence Rule
- Method:
POST - Endpoint:
/api/planning/recurrence/rule/describe - Description: Get human-readable description of a recurrence rule
- Request Payload:
{
"rule": "FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=15"
}
- Response: Description object
Generate Recurrence Instances
- Method:
POST - Endpoint:
/api/planning/recurrence/instances - Description: Generate instances of a recurrence rule
- Request Payload:
{
"rule": "FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=15",
"startDate": "2024-01-15T00:00:00Z",
"endDate": "2024-12-31T23:59:59Z",
"maxCount": 12
}
- Response: Array of generated instance dates
Category Management
List Categories
- Method:
GET - Endpoint:
/api/categories - Description: Get all available categories
- Response: Array of category objects
Create Category
- Method:
POST - Endpoint:
/api/categories - Description: Create a new custom category
- Request Payload:
{
"name": "Custom Category",
"parentId": "uuid",
"color": "#2196F3",
"iconName": "custom-icon"
}
- Response: Created category object
Get Category Details
- Method:
GET - Endpoint:
/api/categories/{id} - Description: Get details of a specific category
- Response: Single category object
Update Category
- Method:
PUT - Endpoint:
/api/categories/{id} - Description: Update an existing category
- Request Payload:
{
"name": "Updated Category Name",
"color": "#4CAF50",
"iconName": "updated-icon"
}
- Response: Updated category object
Delete Category
- Method:
DELETE - Endpoint:
/api/categories/{id} - Description: Delete a custom category
- Response:
204 No Content
Update Transaction Category
- Method:
PATCH - Endpoint:
/api/transactions/{id}/category - Description: Update the category of a transaction
- Request Payload:
{
"categoryId": "uuid",
"learnFromCorrection": true
}
- Response: Updated transaction object
Ensure Default Categories
- Method:
POST - Endpoint:
/api/system/default-categories - Description: Ensure default categories exist for the user
- Response: Status confirmation
Scenario Planning
Create Financial Scenario
- Method:
POST - Endpoint:
/api/planning/scenarios - Description: Create a new financial scenario
- Request Payload:
{
"name": "Job Change Scenario",
"description": "Financial projection if I change jobs",
"baseMonth": "2024-02-01T00:00:00Z",
"duration": 12
}
- Response: Created scenario object
List Scenarios
- Method:
GET - Endpoint:
/api/planning/scenarios - Description: List user's financial scenarios
- Query Parameters:
limit: Numberoffset: Number
- Response: Array of scenario objects with pagination
Get Scenario Details
- Method:
GET - Endpoint:
/api/planning/scenarios/{id} - Description: Get details of a specific scenario
- Response: Single scenario object
Update Scenario
- Method:
PUT - Endpoint:
/api/planning/scenarios/{id} - Description: Update an existing scenario
- Request Payload: Same structure as Create Scenario
- Response: Updated scenario object
Add Scenario Item
- Method:
POST - Endpoint:
/api/planning/scenarios/{id}/items - Description: Add an income or expense item to a scenario
- Request Payload:
{
"name": "New Job Salary",
"description": "Increased salary from new position",
"amount": "6500.00",
"type": "income",
"frequency": "monthly",
"startDate": "2024-03-01T00:00:00Z",
"endDate": "2024-12-31T23:59:59Z",
"growthRate": "0.03"
}
- Response: Created scenario item object
Update Scenario Item
- Method:
PUT - Endpoint:
/api/planning/scenarios/{id}/items/{itemId} - Description: Update a scenario item
- Request Payload: Same structure as Add Scenario Item
- Response: Updated scenario item object
Delete Scenario Item
- Method:
DELETE - Endpoint:
/api/planning/scenarios/{id}/items/{itemId} - Description: Delete a scenario item
- Response:
204 No Content
Calculate Scenario Results
- Method:
POST - Endpoint:
/api/planning/scenarios/{id}/calculate - Description: Calculate financial projections for a scenario
- Response: Calculation results with monthly projections and summary
Compare Scenarios
- Method:
POST - Endpoint:
/api/planning/scenarios/compare - Description: Compare two financial scenarios
- Request Payload:
{
"scenario1Id": "uuid",
"scenario2Id": "uuid"
}
- Response: Comparison object with differences and metrics
Delete Scenario
- Method:
DELETE - Endpoint:
/api/planning/scenarios/{id} - Description: Delete a financial scenario
- Response:
204 No Content
UI Visualization Components
Get Balance Projection Chart
- Method:
GET - Endpoint:
/api/cashflow/ui/balance-projection - Description: Get chart data for balance projection visualization
- Query Parameters:
months: Number (default: 12)chartType: "line", "area" (default: "line")
- Response: Chart data object with labels and datasets
Get Transaction Breakdown Chart
- Method:
GET - Endpoint:
/api/cashflow/ui/transaction-breakdown - Description: Get chart data for transaction breakdown by category
- Query Parameters:
period: StringchartType: "pie", "bar" (default: "pie")
- Response: Chart data object with category breakdowns
Get Cash Flow Health Indicator
- Method:
GET - Endpoint:
/api/cashflow/ui/health-indicator - Description: Get cash flow health score and indicators
- Response: Health indicator object with scores and recommendations
Get Alerts Digest
- Method:
GET - Endpoint:
/api/cashflow/ui/alerts-digest - Description: Get summarized alerts for dashboard display
- Response: Digest object with prioritized alerts
Get Recommendations Digest
- Method:
GET - Endpoint:
/api/cashflow/ui/recommendations-digest - Description: Get financial recommendations for dashboard
- Response: Digest object with personalized recommendations
Get Recurring Transactions View
- Method:
GET - Endpoint:
/api/cashflow/ui/recurring-transactions - Description: Get formatted recurring transactions for UI display
- Response: Formatted recurring transactions array
Get Goal Visualization
- Method:
GET - Endpoint:
/api/goals/ui/visualization/{id} - Description: Get visualization data for a specific goal
- Response: Visualization object with progress charts and milestones
Get Goals Progress Summary
- Method:
GET - Endpoint:
/api/goals/ui/summary - Description: Get overall goals progress summary for dashboard
- Response: Summary object with aggregated goal progress
Get Contribution History Visualization
- Method:
GET - Endpoint:
/api/goals/ui/contributions/{id} - Description: Get contribution history chart data for a goal
- Query Parameters:
months: Number (default: 12)
- Response: Chart data object with contribution timeline
Get Goal Projection Visualization
- Method:
GET - Endpoint:
/api/goals/ui/projections/{id} - Description: Get goal completion projection visualization
- Response: Projection chart data with completion timeline
Forecasting & Suggestions
Get Forecasts
- Method:
GET - Endpoint:
/api/analytics/forecasts - Description: Get spending forecasts
- Query Parameters:
period: "monthly", "quarterly", "yearly"limit: Number (default: 12)startDate: ISO date stringendDate: ISO date string
- Response: Array of forecast objects with predictions
Get Overall Forecast
- Method:
GET - Endpoint:
/api/analytics/forecasts/overall - Description: Get overall spending forecast
- Query Parameters:
period: String (default: "yearly")
- Response: Overall forecast object
Get Category Forecast
- Method:
GET - Endpoint:
/api/analytics/forecasts/category/{id} - Description: Get forecast for a specific category
- Query Parameters:
period: String (default: "monthly")limit: Number (default: 6)
- Response: Category-specific forecast object
Get Merchant Forecast
- Method:
GET - Endpoint:
/api/analytics/forecasts/merchant/{merchantName} - Description: Get forecast for a specific merchant
- Query Parameters:
period: String (default: "monthly")limit: Number (default: 6)
- Response: Merchant-specific forecast object
Regenerate Forecasts
- Method:
POST - Endpoint:
/api/analytics/forecasts/regenerate - Description: Manually trigger forecast regeneration
- Response: Regeneration status confirmation
Get Suggestions
- Method:
GET - Endpoint:
/api/analytics/suggestions - Description: Get financial suggestions
- Query Parameters:
status: "new", "viewed", "implemented", "dismissed"limit: Number (default: 10)suggestionType: StringminSaving: Decimal string
- Response: Array of suggestion objects
Get Top Suggestions
- Method:
GET - Endpoint:
/api/analytics/suggestions/top - Description: Get top financial suggestions by potential saving
- Query Parameters:
limit: Number (default: 5)
- Response: Array of top suggestion objects
Update Suggestion Status
- Method:
PUT - Endpoint:
/api/analytics/suggestions/{id}/status - Description: Update the status of a suggestion
- Request Payload:
{
"status": "implemented"
}
- Response: Updated suggestion object
Generate Suggestions
- Method:
POST - Endpoint:
/api/analytics/suggestions/generate - Description: Manually trigger suggestion generation
- Response: Generation status confirmation
Transactions
Create Transaction
- Method:
POST - Endpoint:
/api/transactions - Description: Manually create a new transaction
- Request Payload:
{
"documentId": "uuid",
"transactionDate": "2024-01-15T00:00:00Z",
"description": "Manual Transaction Entry",
"amount": "-45.67",
"transactionType": "expense",
"categoryId": "uuid",
"merchantName": "Local Store"
}
- Response: Created transaction object
Learn from Categorization Correction
- Method:
POST - Endpoint:
/api/transactions/{id}/learn - Description: Learn from manual categorization correction
- Response: Learning confirmation status
Data Types & Formats
Common Data Types
- UUID:
"550e8400-e29b-41d4-a716-446655440000" - Decimal Amount:
"1234.56"(string with decimal precision) - Negative Amount:
"-1234.56" - Date/Time:
"2024-01-15T10:30:00Z"(ISO 8601 UTC)
Status Values
- Document Status:
pending,processing,completed,failed - Goal Status:
active,achieved,cancelled,on_hold - Budget Period:
weekly,monthly,quarterly,yearly,custom - Priority:
low,medium,high - Alert Severity:
low,medium,high
HTTP Status Codes
200 OK- Success201 Created- Resource created204 No Content- Success, no content400 Bad Request- Invalid request401 Unauthorized- Authentication required403 Forbidden- Access denied404 Not Found- Resource not found422 Unprocessable Entity- Validation error500 Internal Server Error- Server error
Error Response Format
{
"error": "Error message description",
"code": "ERROR_CODE",
"details": {
"field": "validation error message"
},
"timestamp": "2024-01-15T10:30:00Z"
}