Bundle 2 - Results API

Overview

Bundle 2 is Kamoa's most advanced product, delivering real-time, feature-rich credit insights by merging client-submitted statements with Kamoa's alternative-data lake and a live CIK bureau pull. The result is our highest-fidelity score plus a full analytics pack to drive smarter, safer lending decisions.

Key Features

• 🚀 Bundle 1 – Superior predictive score enriched with bureau + alternative data
• 💼 CIK Credit Report – Verified credit history and obligations from CreditInfo Kenya
• 📊 Cash-Flow Analytics – Detailed, parsed metrics directly from the uploaded PDF
• 🗄️ Raw Transaction JSON – Full, structured transaction data for transparency
• ⏱ Real-Time Processing – Score returned seconds after statement upload

---

Input Requirements

Field	Type	Description
nationalId	String	Government-issued ID (Passport/ID Card)
firstName	String	Client's legal first name
lastName	String	Client's legal surname
statement	PDF File	Bank or mobile-money statement

Important: Statement freshness and coverage directly impact score accuracy. Provide 6-12 months of data for optimal results.

---

Endpoint

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

Example Request

curl -X GET "https://api.kamoa.io/score/results/your-request-id" \
  -H "Authorization: Bearer YOUR_AUTH_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	{token}	Auth token for authentication
Content-Type	application/json	Request content type

---

Response Structure

The API response remains lightweight. It returns presigned links; all analytical content (summary, persona, cash-flow, borrowing character, recommendations, score, cikReport) is stored inside the files referenced by those links.

Top-level fields:

• featurizedUrls – Pre-signed URLs to the fully processed, model-ready JSON
• parsedUrls – Pre-signed URLs to raw parsed transaction JSON
• score – Bundle 2 (0-1000) for quick access
• cikReport – Raw CIK credit-report string
• requestId – Same UUID you supplied when you requested the report
• productCode – Always "P8" for Bundle 2

Root Response

{
  "parsedUrls": ["https://s3-presigned-url/parsed.json?..."],
  "featurizedUrls": ["https://s3-presigned-url/features.json?..."],
  "score": 673,
  "cikReport": "{...}",
  "requestId": "uuid-string",
  "productCode": "P8"
}

---

Summary Block (inside featurized file)

Provides critical top-level insights and credit recommendations.

Field	Type	Description
recommended_credit_limit.short_term	Number	Low-risk loan limit suggestion
confidence_level	String	Data reliability indicator (e.g. "100%")
risk_summary	String	Risk band, default probability & decision
customer_profile	String	Depth of user information processed
key_insights	Array	Behavioural patterns (e.g., "No Savings")

(additional fields mirror those in the Score360 documentation)

---

Persona, Data Completeness, Cash Flow, Borrowing Character (featurized file)

These sections replicate the schemas described in Score360 but are derived directly from the uploaded statement, offering real-time insights. Refer to those tables for field-level details.

---

Recommendations Block (featurized file)

Delivers behavioural scores and income-based loan recommendations.

Field	Type	Description
short_term_score	Number	Score from short-term M-Pesa loan behaviour
business_score	Number	Score from business wallet/till activity
generic_score	Number	Composite creditworthiness score (0-1000)
short_term_affordability	Number	Max affordable short-term loan amount
business_affordability	Number	Max affordable business loan amount or null

---

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	Resource not found
500	Internal server error

---

Usage Example

// 1. Get the root response
const res = await fetch(`/score/results/${requestId}`, {
  headers: { Authorization: authToken },
});
const root = await res.json();

// 2. Download the featurized file
const featRes = await fetch(root.featurizedUrls[0]);
const data = await featRes.json();

// 3. Access analytics
const boostedScore = data.score;
const cikReport = data.cikReport;

Best Practices

• Pre-signed URLs expire after 10 minutes – download promptly

---

Working with Featurized Data

Download the first URL in featurizedUrls within 10 minutes (URL expiry) and parse the JSON. Inside you will find:

{
  "score": 673,              // Bundle 2 (0-1000)
  "cikReport": "{...}",     // Raw CIK credit report
  "summary": { ... },        // Same schema as Score360
  "persona": { ... },
  "data_completeness": { ... },
  "cashflow": { ... },
  "borrowing_character": { ... },
  "recommendations": { ... }
}

Use these blocks exactly as documented in the Score360 results. Only the container (presigned file) differs; the internal schema is identical.

ℹ️ The API keeps payloads small; all heavy analytics live in the downloadable JSON.