Kamoa360 - Results API

Overview

The Kamoa360 API provides comprehensive financial analysis and credit risk assessment by analyzing transaction patterns, income stability, and borrowing behavior. This endpoint delivers in-depth insights for advanced lending decisions through sophisticated scoring algorithms and detailed financial profiling.

Key Features

🔍 Comprehensive Analysis – Deep financial behavior insights and risk assessment
📊 Multi-dimensional Scoring – Credit scores based on various financial factors
💰 Affordability Assessment – Data-driven loan limit recommendations
👤 Customer Profiling – Detailed persona and lifestyle analysis
📈 Cash Flow Analysis – Income patterns and financial stability metrics

Product Differentiation

Use the productCode field to distinguish between responses:

PA: Raw parsed data only (See Extract & Authenticate Section)
PAS: Basic scored data with recommendations (See KamoaLite Section)
PARS: Advanced financial analysis and profiling (See Kamoa360 Section)

Endpoint

GET https://api.kamoa.io/score/results/{requestId}

Example Request

curl -X GET "https://api.kamoa.io/score/results/c2a315ac-ed11-4462-bb78-24c5fa9b480d" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Request Details

Component	Value
Base URL	`https://api.kamoa.io`
Endpoint	`/score/results/{requestId}`
Method	`GET`
Path Parameter	`requestId` - UUID from initial submit

Required Headers

Header	Value	Description
`Authorization`	`Bearer {token}`	JWT token for authentication
`Content-Type`	`application/json`	Request content type

Response Structure

The API returns a structured JSON response containing detailed financial analysis organized into six main sections:

Summary: High-level assessment and recommendations
Persona: Customer profile and behavioral indicators
Data Completeness: Statement coverage and data quality metrics
Cash Flow: Income patterns and financial health indicators
Borrowing Character: Loan and overdraft usage analysis
Lifestyle: Spending patterns and behavioral insights

API Response Schema

Root Response

{
  "status": "success",
  "code": 200,
  "data": {
    "summary": {...},
    "persona": {...},
    "data_completeness": {...},
    "cashflow": {...},
    "borrowing_character": {...},
    "recommendations": {...},
    "lifestyle": {...}
  }
}

Summary Section

Provides executive-level insights and credit recommendations.

Overall Customer Assessment

Field	Type	Description
`recommended_credit_limit.short_term_limit`	Number	Maximum affordable short-term loan amount
`recommended_credit_limit.business_limit`	Number\|null	Maximum affordable business loan amount
`confidence_level`	String	Data accuracy confidence (e.g., "100%")

Risk Assessment

Field	Type	Description
`risk_summary`	String	Risk band with default probability and decision
`risk_mitigation_block`	String	Additional risk mitigation guidance

Example Risk Bands:

A (2% default risk) → Approve
B (5% default risk) → Approve with conditions
C (15% default risk) → Decline

Key Insights

Field	Type	Description
`observed_monthly_income`	Number	Median monthly cashflow from inflows
`average_monthly_borrowing`	Number	Average loan amount per active borrowing month
`average_monthly_overdraft_usage`	Number	Average overdraft usage per active month
`main_outflow_categories`	Array	Top spending categories with amounts
`customer_behaviour_identified`	Array	Detected behavioral patterns

Persona Section

Contains customer identification and behavioral profiling.

Personal Information

Field	Type	Description
`name`	String	Full name from statement
`phone_number`	String	Phone number from statement
`has_salary`	Boolean	Receives regular salary payments
`has_till_account`	Boolean	Operates a business till account
`has_pochi_wallet`	Boolean	Uses business wallet services
`has_bank_account`	Boolean	Has linked bank account
`main_bank`	String\|null	Primary bank for income
`earning_profile`	String	Income type: "formal", "informal", or "mixed"
`is_a_driver`	Boolean	Likely works as a driver (based on fuel spending)

Data Completeness Section

Evaluates the quality and coverage of the financial statement.

Field	Type	Description
`statement_period`	String	Date range covered (YYYY-MM-DD format)
`completeness_flag`	String	Coverage quality indicator
`nb_months_in_statement`	Number	Total months covered
`transaction_count`	Number	Total number of transactions
`transaction_days`	Number	Days with at least one transaction

Completeness Flags:

Green (100% of months covered) - Complete data
Yellow (80-99% of months covered) - Mostly complete
Red (<80% of months covered) - Incomplete data

Cash Flow Section

Analyzes income patterns, balance stability, and financial health.

Core Metrics

Field	Type	Description
`cash_inflow_ratio`	String	Percentage of inflows from cash deposits
`cash_outflow_ratio`	String	Percentage of outflows to cash withdrawals
`observed_income_block`	Object	Median monthly income and active months
`estimated_monthly_income`	Object	Calculated monthly income estimate
`average_daily_income`	Number	Average daily income from inflows
`debt_to_income_ratio`	Number\|null	Ratio of loan disbursements to income

Balance and Stability

Field	Type	Description
`average_daily_balance`	Number	Average end-of-day balance
`days_with_low_balance`	Number	Days with critically low balance
`snapshot_date`	String	Date of most recent transaction

Time Series Data

Field	Type	Description
`monthly_income_evolution`	Array	Monthly income over time
`evolution_of_cashflow`	Array	Monthly inflows vs outflows

Monthly Income Evolution Format:

[
  {
    "month": "2024-01",
    "income": 147399
  }
]

Cash Flow Evolution Format:

[
  {
    "month": "2024-01", 
    "inflow": 147399,
    "outflow": 146069
  }
]

Borrowing Character Section

Analyzes loan behavior, repayment patterns, and overdraft usage.

Loan Disbursements

Field	Type	Description
`nb_disb_events`	Number	Total disbursement events
`total_disbursed`	Number	Total amount disbursed
`avg_disb_per_event`	Number	Average disbursement per event
`highest_disbursement`	Number	Largest single disbursement

Loan Repayments

Field	Type	Description
`nb_repay_events`	Number	Total repayment events
`total_repaid`	Number	Total amount repaid
`avg_repay_per_event`	Number	Average repayment per event
`highest_repayment`	Number	Largest single repayment

Overdraft Usage

Field	Type	Description
`nb_overdraft_events`	Number	Total overdraft events
`total_overdraft`	Number	Total overdraft amount used
`avg_overdraft_per_event`	Number	Average overdraft per event
`highest_overdraft`	Number	Highest single overdraft

Recommendations Section

Provides credit scores and loan affordability assessments.

Credit Scores

Field	Type	Description
`short_term_score`	Number	Score for short-term M-Pesa loans (0-1000)
`bwc_score`	Number	Business wallet/till loan score (-1 if N/A)
`generic_score`	Number	Composite creditworthiness score (0-1000)

Affordability Limits

Field	Type	Description
`short_term_affordability`	Number	Maximum short-term loan amount
`business_affordability`	Number\|null	Maximum business loan amount

Score Interpretation:

800-1000: Excellent credit profile
600-799: Good credit profile
400-599: Fair credit profile
200-399: Poor credit profile
0-199: High risk profile
-1: Insufficient data

Lifestyle Section

Analyzes spending patterns and behavioral indicators.

Spending Categories

Field	Type	Description
`top_spending_categories`	Array	Breakdown of major spending categories

Category Format:

[
  {
    "category": "saving deposit",
    "value": 2046405.0
  }
]

Common Categories:

saving deposit - Money saved/invested
sent to individual - Person-to-person transfers
sent to business - Business payments
sent to individual via overdraft - P2P transfers using overdraft
sent to business via payment solution - Business payments via payment platforms

Utility Payments

Field	Type	Description
`utilities_payments`	Array	Regular utility payment patterns

Utility Format:

[
  {
    "name": "Electricity Prepaid",
    "amount": 229,
    "frequency": 36
  }
]

Retail Spending

Field	Type	Description
`top_supermarkets_visited`	Array	Top 5 retail spending locations

Supermarket Format:

[
  {
    "label": "Carrefour",
    "value": 35086.0
  }
]

Behavioral Indicators

Field	Type	Description
`customer_behaviour`	Array	Detected behavioral patterns

Behavior Format:

[
  {
    "title": "Business activity",
    "status": false
  },
  {
    "title": "Betting", 
    "status": false
  },
  {
    "title": "Savings",
    "status": true
  }
]

Visual Display Types

The API includes visual display indicators for UI rendering:

Visual Type	Description	Use Case
`metric_card`	Single metric display	KPIs, scores, amounts
`double_metric_card`	Two related metrics	Comparisons
`text`	Simple text display	Labels, categories
`text_block`	Longer text content	Descriptions, advice
`tag`	Boolean/status indicator	Yes/no, true/false
`pie`	Pie chart visualization	Category breakdowns
`bar`	Bar chart	Time series, comparisons
`bar_chart_grouped`	Grouped bar chart	Multi-series data
`bar_horizontal`	Horizontal bar chart	Rankings, lists
`pill`	Status pills/badges	Multiple status indicators

Error Handling

Success Response

{
  "status": "success",
  "code": 200,
  "data": {...}
}

Error Response Format

{
  "status": "error", 
  "code": 400,
  "message": "Error description",
  "details": "Additional error context"
}

Common Error Codes

Code	Description
400	Invalid request format or missing parameters
401	Authentication required
403	Insufficient permissions
404	Statement or resource not found
422	Unprocessable statement data
500	Internal server error

Usage Examples

Basic Request

curl -X POST "https://api.example.com/featureizer" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "statement_data": "...",
    "phone_number": "254792645945"
  }'

Processing the Response

// Extract key insights
const response = await fetch('/featureizer', {
  method: 'POST',
  body: JSON.stringify(statementData)
});

const result = await response.json();

if (result.status === 'success') {
  const {
    summary,
    cashflow, 
    borrowing_character,
    recommendations
  } = result.data;

  // Get credit recommendation
  const creditLimit = summary.overall_customer_assessment
    .recommended_credit_limit.short_term_limit;

  // Get risk assessment  
  const riskSummary = summary.recommended_decision.risk_summary;

  // Get monthly income
  const monthlyIncome = cashflow.observed_income_block.median;

  // Get credit score
  const creditScore = recommendations.short_term_score;
}

Best Practices

Data Quality

Ensure statement covers at least 6 months for reliable analysis
Complete transaction data improves accuracy of insights
Regular statement updates provide better trend analysis

Credit Assessment

Use confidence_level to gauge reliability of recommendations
Consider risk_mitigation_block for additional context
Cross-reference multiple scores for comprehensive assessment

Behavioral Analysis

Combine spending categories with behavioral indicators
Monitor income evolution trends for stability assessment
Use utility payments as stability indicators

Implementation

Cache results appropriately based on statement recency
Implement proper error handling for all response codes
Use visual display types for consistent UI rendering

Overview​

Key Features​

Endpoint​

Example Request​

Request Details​

Required Headers​

Response Structure​

API Response Schema​

Root Response​

Summary Section​

Overall Customer Assessment​

Risk Assessment​

Key Insights​

Persona Section​

Personal Information​

Data Completeness Section​

Cash Flow Section​

Core Metrics​

Balance and Stability​

Time Series Data​

Borrowing Character Section​

Loan Disbursements​

Loan Repayments​

Overdraft Usage​

Recommendations Section​

Credit Scores​

Affordability Limits​

Lifestyle Section​

Spending Categories​

Utility Payments​

Retail Spending​

Behavioral Indicators​

Visual Display Types​

Error Handling​

Success Response​

Error Response Format​

Common Error Codes​

Usage Examples​

Basic Request​

Processing the Response​

Best Practices​

Data Quality​

Credit Assessment​

Behavioral Analysis​

Implementation​