InfraForge Docs

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 string
    • endDate: ISO date string
    • period: "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
  • 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 string
    • endDate: ISO date string
    • minSignificance: Number (0-1)
    • limit: Number
  • Response: Array of trend objects with significance scores
  • 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 name
    • period: String - filter by budget period
    • isActive: Boolean - filter by active status
    • startDateFrom: ISO date string
    • startDateTo: ISO date string
    • includeInactive: Boolean
    • limit: Number
    • offset: 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 filter
    • priority: "low", "medium", "high"
    • limit: Number
    • offset: 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: Number
    • offset: 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 string
    • endDate: ISO date string
    • limit: 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: Number
    • offset: Number
    • isPaid: Boolean
    • categoryId: 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: Number
    • offset: 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: String
    • chartType: "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 string
    • endDate: 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: String
    • minSaving: 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 - Success
  • 201 Created - Resource created
  • 204 No Content - Success, no content
  • 400 Bad Request - Invalid request
  • 401 Unauthorized - Authentication required
  • 403 Forbidden - Access denied
  • 404 Not Found - Resource not found
  • 422 Unprocessable Entity - Validation error
  • 500 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"
}