KamoaLite - Results API

Overview

The KamoaLite API provides comprehensive credit risk assessments by analyzing financial statements from mobile money and banking data. This endpoint delivers actionable insights for lending decisions through advanced scoring algorithms and affordability calculations.

Key Features

⚡ Instant Risk Assessment – Get credit scores within seconds of document upload
🎯 Multi-factor Analysis – Combines income verification, spending patterns, and repayment history
📊 Three Specialized Scores – Different risk models for various lending scenarios
💰 Affordability Metrics – Data-driven loan limit recommendations
🔍 Decision Support – Clear approval recommendations with detailed risk tiers

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

{
  "parsedUrls": ["https://s3-presigned-url..."],
  "recommendations": {
    "title": "Recommendations",
    "description": "Behavioral score and income-based loan recommendations.",
    "blocks": {
      "short_term_score": { /* Score details */ },
      "bwc_score": { /* Score details */ },
      "generic_score": { /* Score details */ },
      "short_term_affordability": { /* Affordability details */ },
      "business_affordability": { /* Affordability details */ }
    }
  },
  "requestId": "uuid-string",
  "productCode": "PAS"
}

Field	Type	Description
`parsedUrls`	`string[]`	Pre-signed S3 URLs for accessing parsed financial data (10 minutes)
`recommendations`	`object`	Credit scoring and affordability analysis
`requestId`	`string`	Unique identifier matching your initial request
`productCode`	`string`	Always `"PAS"` for scored responses

parsedUrls

Pre-signed URLs to retrieve raw parsed data.

"parsedUrls": [
  "https://example.s3.amazonaws.com/documents/parsed/c2a315ac-ed11-4462-bb78-24c5fa9b480d/parsed.json?AWSAccessKeyId=AKIA...&Expires=1640995200&Signature=..."
]

Recommendations Blocks

The recommendations.blocks object contains five distinct payloads:

Three Score Blocks
Two Affordability Blocks

Short Term Score

Field	Type	Description
`theme`	string	`"Borrowing Character"`
`title`	string	`"Short Term Score"`
`description`	string	Score based on short-term M-PESA loan behavior
`content`	number	Risk score value (e.g. 350)
`display`	boolean	Whether this score is visible in the UI
`visual`	string	`"metric_card"` – rendering hint

"short_term_score": {
  "theme": "Borrowing Character",
  "title": "Short Term Score",
  "description": "Score based on short term M-PESA loans.",
  "content": 350,
  "display": true,
  "visual": "metric_card"
}

Business Wallet Score (BWC)

Field	Type	Description
`theme`	string	`"Borrowing Character"`
`title`	string	`"Business Score"`
`description`	string	Business till/wallet loan repayment risk
`content`	number	`-1` means insufficient data; otherwise, score value
`display`	boolean	UI display flag
`visual`	string	`"metric_card"`

"bwc_score": {
  "theme": "Borrowing Character",
  "title": "Business Score",
  "description": "Score based on business wallet/till loan activity.",
  "content": -1,
  "display": true,
  "visual": "metric_card"
}

Generic Score

Field	Type	Description
`theme`	string	`"Borrowing Character"`
`title`	string	`"Generic Score"`
`description`	string	Composite score including savings, income, and cash flow
`content`	number	Score from 0 to 1000
`display`	boolean	Visibility toggle
`visual`	string	`"metric_card"`

"generic_score": {
  "theme": "Borrowing Character",
  "title": "Generic Score",
  "description": "Composite score based on multiple financial factors.",
  "content": 962,
  "display": true,
  "visual": "metric_card"
}

Short Term Affordability

Field	Type	Description
`theme`	string	`"Cash Flow"`
`title`	string	`"Short Term Affordability"`
`description`	string	Max 30-day loan amount customer can afford
`content`	number	Monetary amount (e.g., `2825`)
`display`	boolean	Whether to show the metric
`visual`	string	`"metric_card"`

"short_term_affordability": {
  "theme": "Cash Flow",
  "title": "Short Term Affordability",
  "description": "Max affordable short term loan limit.",
  "content": 2825,
  "display": true,
  "visual": "metric_card"
}

Business Affordability

Field	Type	Description
`theme`	string	`"Cash Flow"`
`title`	string	`"Business Affordability"`
`description`	string	Based on income from a business wallet/till
`content`	number/null	Loan amount or `null` if not available
`display`	boolean	UI display toggle
`visual`	string	`"metric_card"`

"business_affordability": {
  "theme": "Cash Flow",
  "title": "Business Affordability",
  "description": "Max affordable business loan limit.",
  "content": null,
  "display": false,
  "visual": "metric_card"
}

Full Example Response

{
  "parsedUrls": [
    "https://example.s3.amazonaws.com/documents/parsed/c2a315ac-ed11-4462-bb78-24c5fa9b480d/parsed.json?AWSAccessKeyId=AKIA...&Expires=1640995200&Signature=..."
  ],
  "recommendations": {
    "title": "Recommendations",
    "description": "Behavioral score and income-based loan recommendations.",
    "blocks": {
      "short_term_score": {
        "theme": "Borrowing Character",
        "title": "Short Term Score",
        "description": "Score based on short term M-PESA loans.",
        "content": 350,
        "display": true,
        "visual": "metric_card"
      },
      "bwc_score": {
        "theme": "Borrowing Character",
        "title": "Business Score",
        "description": "Score based on business wallet/till loan activity.",
        "content": -1,
        "display": true,
        "visual": "metric_card"
      },
      "generic_score": {
        "theme": "Borrowing Character",
        "title": "Generic Score",
        "description": "Composite score based on multiple financial factors.",
        "content": 962,
        "display": true,
        "visual": "metric_card"
      },
      "short_term_affordability": {
        "theme": "Cash Flow",
        "title": "Short Term Affordability",
        "description": "Max affordable short term loan limit.",
        "content": 2825,
        "display": true,
        "visual": "metric_card"
      },
      "business_affordability": {
        "theme": "Cash Flow",
        "title": "Business Affordability",
        "description": "Max affordable business loan limit.",
        "content": null,
        "display": false,
        "visual": "metric_card"
      }
    }
  },
  "requestId": "c2a315ac-ed11-4462-bb78-24c5fa9b480d",
  "productCode": "PAS"
}

Product Comparison

Feature	PA Response	PAS Response	PARS Response
Product Code	`"PA"`	`"PAS"`	`"PARS"`
Primary Use Case	Raw data access and custom analysis	Ready-to-use credit decisions	Advanced financial profiling
Credit Scores	❌ Not included	✅ Three specialized scores	✅ Comprehensive scoring models
Affordability Analysis	❌ Not included	✅ Basic loan limits	✅ Detailed affordability metrics
Risk Assessment	❌ Manual analysis required	✅ Basic scoring models	✅ Advanced risk categorization
Decision Support	❌ Raw data only	✅ Basic recommendations	✅ Comprehensive decision guidance
Customer Profiling	❌ Not included	❌ Limited profiling	✅ Detailed persona analysis
Integration Complexity	High – requires custom scoring	Medium – some customization	Low – comprehensive out-of-the-box
Best For	Fintech teams with ML capabilities	Credit teams & lending platforms	Advanced risk assessment operations

Overview​

Key Features​

Endpoint​

Example Request​

Request Details​

Required Headers​

Response Structure​

parsedUrls​

Recommendations Blocks​

Short Term Score​

Business Wallet Score (BWC)​

Generic Score​

Short Term Affordability​

Business Affordability​

Full Example Response​

Product Comparison​