Skip to main content
Finora Business
Finora Business
Sign InStart Free Trial

Reference

Digital Officer / AI

Enterprise only

Proactive financial health alerts, rule-based product recommendations, and a natural-language query endpoint over the business's financials.

The AI module exposes three capabilities powered by Finora Business's real-time financial data: proactive health alerts (usually called on a schedule), rule-based product recommendations, and a natural-language Q&A endpoint.

Generate health alerts

POST/v1/businesses/{businessId}/ai/health-alerts

Triggers an analysis of the business's current financial state and generates proactive alerts where issues are detected.

Typically called on a schedule (daily or weekly) by your backend so that account officers receive a curated list of businesses needing attention.

Body

FieldTypeRequiredNotes
analysisDepthstringnoquick (revenue + cash only) or full (all metrics). Default full.
compareToSectorbooleannoInclude sector benchmark comparison. Default true.

Response — 200

{
  "success": true,
  "data": {
    "businessId": "biz_002",
    "analysisDate": "2026-04-17T10:30:00.000Z",
    "alertsGenerated": 3,
    "alerts": [
      {
        "alertId": "ai_alert_001",
        "type": "declining_revenue",
        "severity": "critical",
        "headline": "Revenue Declining Sharply — Down 23% in 3 Months",
        "description": "Revenue has declined from NGN 3.2M in January to NGN 2.1M in March...",
        "metrics": [
          { "label": "Monthly Revenue", "current": "NGN 2.1M", "previous": "NGN 2.7M (3mo avg)", "change": "-23%" },
          { "label": "Cash Position", "current": "NGN 350K", "previous": "NGN 800K", "change": "-56%" }
        ],
        "suggestedActions": [
          "Schedule a cash-flow recovery conversation with the owner",
          "Review loan covenant status — cash balance approaching threshold",
          "Push for collections on overdue receivables"
        ],
        "sectorComparison": {
          "sector": "logistics",
          "avgRevenueGrowth": "+4.2%",
          "businessRevenueGrowth": "-23%",
          "percentile": 5
        }
      }
    ]
  }
}

Alert severity values are critical, warning, and info. The checks cover overdue invoices, negative cash flow, covenant proximity, tax compliance lapses, and sector-relative underperformance.

Product recommendations

GET/v1/businesses/{businessId}/ai/recommendations

Rule-based product and action recommendations tailored to the business's financial state.

Response — 200

{
  "success": true,
  "data": {
    "businessId": "biz_003",
    "computedAt": "2026-04-17T10:30:00.000Z",
    "recommendations": [
      {
        "recommendationId": "rec_001",
        "category": "investment",
        "title": "Put Idle Cash to Work",
        "description": "You have NGN 8.5M sitting idle for 60+ days. T-bills could earn ~NGN 1.5M annually.",
        "suggestedProduct": "Fixed Deposit / Treasury Bills",
        "potentialValueKobo": 153000000,
        "confidence": 0.92,
        "ctaLabel": "Explore Investment Options",
        "ctaAction": "open_investment_page"
      },
      {
        "recommendationId": "rec_002",
        "category": "collections",
        "title": "Speed Up Receivables",
        "description": "17% of receivables are aged beyond 30 days.",
        "suggestedProduct": "Automated Payment Reminders",
        "potentialValueKobo": 15000000,
        "confidence": 0.75,
        "ctaLabel": "Enable Auto-Reminders",
        "ctaAction": "enable_reminders"
      }
    ]
  }
}

Categories cover investment, collections, lending, tax, payroll, and payments. Use ctaAction to deep-link into the Finora Business dashboard or your own surface.

Natural-language query

POST/v1/businesses/{businessId}/ai/ask

Accepts a natural-language question about the business's finances and returns an AI-generated answer with supporting data.

Body

FieldTypeRequiredNotes
questionstringyesMax 500 characters.
contextstringnobusiness_owner, account_officer, or branch_manager. Affects response detail level. Default business_owner.

Response — 200

{
  "success": true,
  "data": {
    "businessId": "biz_001",
    "question": "What's my cash position and how long will it last?",
    "answer": "Your current cash position is NGN 1.2M across all accounts. Based on your average monthly expenses of NGN 280K, cash runway is ~4.3 months...",
    "supportingData": {
      "cashPositionKobo": 120000000,
      "bankBalanceKobo": 105000000,
      "cashBalanceKobo": 15000000,
      "monthlyAvgExpensesKobo": 28000000,
      "cashRunwayMonths": 4.3,
      "cashTrend3Month": "+15%"
    },
    "relatedQuestions": [
      "What are my biggest expenses this month?",
      "Which customers owe me money?",
      "Am I eligible for a loan?"
    ],
    "confidence": 0.95,
    "computedAt": "2026-04-17T10:30:00.000Z"
  }
}

403 response for retail keys

{
  "success": false,
  "error": {
    "code": "ENTERPRISE_ONLY",
    "message": "This endpoint requires an enterprise subscription. Contact sales at https://finorabusiness.com/contact",
    "requestId": "req_..."
  }
}

Building conversational finance into your app?

The AI module is part of the enterprise tier — usage is metered separately from standard API calls because of the underlying compute cost. Contact sales to discuss a deployment.

Related endpoints

Reference index

Back to all modules