Score Request API

Overview

The Score Request API allows you to request credit scores and related financial products. This endpoint processes customer information and returns scoring results based on the selected product type.

Endpoint

POST https://api.kamoa.io/score/request

info

This endpoint processes customer information and returns scoring results based on the selected product type.

Authentication

For detailed instructions, see the Authentication Guide.

• Authorization: token
• x-api-key: Your API key

Security Note

Never expose API keys in client-side code

cURL Example

curl -X POST https://api.kamoa.io/score/request \
  -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "x-api-key: secret_IPU5xWuAwimnyTGLlPGaCw8AY..." \
  -H "Content-Type: application/json"

Request Headers

Header	Required	Description
Content-Type	Yes	Must be application/json
Authorization	Yes	token for authentication
x-api-key	Yes	Your API key for additional security

Request Body

Required Fields

Field	Type	Description	Validation
nationalId	string	Customer's national ID number	Required, non-empty
phoneNumber	string	Customer's phone number	Required, must be valid international format
firstName	string	Customer's first name	Required, non-empty
lastName	string	Customer's last name	Required, non-empty
productCode	enum	Product type to request	Must be one of the available product codes

Optional Fields

Field	Type	Description	Validation
email	string	Customer's email address	Optional, valid email format if provided
street	string	Street address	Optional
city	string	City	Optional
country	string	Country	Optional
middleName	string	Customer's middle name	Optional
kraPin	string	Kenya Revenue Authority PIN	Optional
dob	string	Date of birth	Optional, ISO date format
augment	boolean	Augment analysis with extra datasets	Optional, default false
documentsDetails	array	List of documents with details	Required for statement-based products

Document Details Object

Field	Type	Description	Validation
name	string	Document file name	Required
type	enum	Type of document to analyze	Required (MPESA_STATEMENT, BANK_STATEMENT, etc.)
password	string	Password for protected statements	Required for M-Pesa statements
bankName	enum	Bank name (UPPERCASE with underscores)	Required for bank statements

---

Upload Response & Document Upload

After submitting a request with documents, the API returns pre-signed upload URLs for each document. Use these URLs to upload your files.

Example Response

{
  "message": "Request submitted successfully",
  "requestId": "cd81b45e-2ad4-4ec4-977d-712eb0275508",
  "documents": [
    {
      "documentName": "foimpesa.pdf",
      "documentType": "MPESA_STATEMENT",
      "url": "https://...",
      "expiresAt": "2025-08-25T11:59:10.449Z"
    },
    {
      "documentName": "Mercy_loop.pdf",
      "documentType": "BANK_STATEMENT",
      "url": "https://...",
      "expiresAt": "2025-08-25T11:59:10.481Z"
    }
  ],
  "totalDocuments": 2
}

How to Upload

1. Match local files to the response: Use the documentName field to identify which local file maps to which pre-signed url.
2. Perform a direct upload: Send an HTTP PUT request to the url with the raw file bytes.

cURL Upload Example

curl -X PUT "https://..." \
  -H "Content-Type: application/pdf" \
  --data-binary @foimpesa.pdf

3. Repeat for each document until all uploads are complete.
4. Ensure timing: Uploads must be completed before the expiresAt timestamp.

---

Product Codes

Parsing

Code	Name	Description	Requirements
PA	Extract & Authenticate	Extracts headers and transactions, validates statement authenticity. Returns structured data (CSV/JSON)	Statement PDF required
PAS	KamoaLite	Extract & Authenticate + provides risk score and credit limit for quick underwriting decisions	Statement PDF required
PARS	Kamoa360	KamoaLite + detailed financial behavior signals (income volatility, lifestyle, spend stability)	Statement PDF required

Score

Code	Name	Description	Requirements
P7	Bundle 1	CIK Report + Bundle 1
P8	Bundle 2	Bundle 1 + KamoaLite (CIK report + boosted score + cash flow analysis)	Statement PDF

... (rest of doc unchanged) |

Product Codes

Parsing

Code	Name	Description	Requirements
PA	Extract & Authenticate	Extracts headers and transactions, validates statement authenticity. Returns structured data (CSV/JSON)	Statement PDF required
PAS	KamoaLite	Extract & Authenticate + provides risk score and credit limit for quick underwriting decisions	Statement PDF required
PARS	Kamoa360	KamoaLite + detailed financial behavior signals (income volatility, lifestyle, spend stability)	Statement PDF required

Score

Code	Name	Description	Requirements
P7	Bundle 1	CIK Report + Bundle 1
P8	Bundle 2	Bundle 1 + KamoaLite(CIK report + boosted score + cash flow analysis)	Statement PDF

Use Cases by Product

For Credit Analysts & Data Scientists

• Extract & Authenticate: Raw transaction data for building custom decision models
• Kamoa360: Comprehensive financial behavior analysis with 100+ cash flow features

For Underwriters & Quick Decisions

• KamoaLite: Instant risk scoring and credit limit recommendations
• Bundle 1: Enhanced scoring combining traditional and alternative data
• Bundle 2: Complete credit assessment with all available data sources

Supported Document Types

Type	Description	Additional Requirements
MPESA_STATEMENT	M-Pesa transaction statement	Requires password
MPESA_TILL_STATEMENT	M-Pesa till statement	Requires password
BANK_STATEMENT	Bank account statement	Requires bankName

Supported Banks

Bank Code	Bank Name
KCB	Kenya Commercial Bank
Equity Bank	Equity Bank
NCBA	NCBA Bank
NCBA Loop	NCBA Loop
Absa Bank Kenya	Absa Bank Kenya
Diamond Trust Bank	Diamond Trust Bank
Stanbic Bank Kenya	Stanbic Bank Kenya
Standard Chartered Bank Kenya	Standard Chartered Bank Kenya
I & M Bank	I&M Bank
Prime Bank	Prime Bank
Branch Microfinance	Branch Microfinance
Family Bank	Family Bank

Validation Rules

Conditional Requirements

Important Validation Rules

1. Document Type Requirement: For statement-based product codes (PA, PAS, PARS, P8), the documentType field is required.

2. M-Pesa Statement Requirements: When documentType is MPESA_STATEMENT or MPESA_TILL_STATEMENT, the password field is required.

3. Bank Statement Requirements: When documentType is BANK_STATEMENT, the bankName field is required.

Example Requests

Extract & Authenticate Request

POST /score/request - Extract & Authenticate Product (Multi-Document)

{
  "nationalId": "12345678",
  "phoneNumber": "+254712345678",
  "firstName": "John",
  "lastName": "Doe",
  "productCode": "PA",
  "documents": [
    {
      "documentType": "MPESA_STATEMENT",
      "documentName": "mpesa_statement.pdf",
      "password": "mpesa_password_123"
    }
  ]
}

KamoaLite Request

POST /score/request - KamoaLite Product (Multi-Document)

{
  "nationalId": "12345678",
  "phoneNumber": "+254712345678",
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "middleName": "Smith",
  "productCode": "PAS",
  "documents": [
    {
      "documentType": "BANK_STATEMENT",
      "documentName": "bank_statement.pdf",
      "bankName": "KCB",
      "accountNumber": "1234567890"
    }
  ]
}

Bundle 2 Request

POST /score/request - Bundle 2 Product (Multi-Document)

{
  "nationalId": "12345678",
  "phoneNumber": "+254712345678",
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "middleName": "Smith",
  "street": "123 Main Street",
  "city": "Nairobi",
  "country": "Kenya",
  "kraPin": "A123456789B",
  "dob": "1990-01-15",
  "productCode": "P8",
  "documents": [
    {
      "documentType": "BANK_STATEMENT",
      "documentName": "equity_statement.pdf",
      "bankName": "EQUITY_BANK",
      "accountNumber": "9876543210"
    }
  ]
}

Bundle 1 Request

POST /score/request - Bundle 1 Product (Multi-Document)

{
  "nationalId": "12345678",
  "phoneNumber": "+254712345678",
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "middleName": "Smith",
  "street": "123 Main Street",
  "city": "Nairobi",
  "country": "Kenya",
  "productCode": "P7",
  "documents": []
}

Response Format

Success Response (200 OK)

Multi-Document Success Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "requestId": "req_1234567890abcdef",
  "uploadUrls": [
    {
      "documentName": "mpesa_statement.pdf",
      "url": "https://...",
      "expiresAt": "2024-06-10"
    },
    {
      "documentName": "bank_statement.pdf",
      "url": "https://...",
      "expiresAt": "2024-06-10"
    }
  ]
}

Error Responses

Validation Error (400 Bad Request)

400 Bad Request

{
  "success": false,
  "error": "ValidationError",
  "message": "Request validation failed",
  "details": [
    {
      "field": "phoneNumber",
      "message": "Invalid phone number"
    },
    {
      "field": "documentType",
      "message": "Document type is required for statement-based products"
    }
  ]
}

Authentication Error (401 Unauthorized)

401 Unauthorized

{
  "success": false,
  "error": "AuthenticationError",
  "message": "Invalid or expired authentication token"
}

Rate Limit Error (429 Too Many Requests)

429 Too Many Requests

{
  "success": false,
  "error": "RateLimitError",
  "message": "Too many requests. Please try again later.",
  "retryAfter": 60,
  "quotaRemaining": 847,
  "resetTime": "2025-06-10T15:30:00Z"
}

Error Codes

HTTP Status	Error Type	Description	Common Causes
400	ValidationError	Request data validation failed	Missing required fields, invalid format
401	AuthenticationError	Invalid or missing authentication	Expired token, missing API key
403	AuthorizationError	Insufficient permissions	Invalid API key, plan restrictions
429	RateLimitError	Rate or quota limit exceeded	Too many requests, daily quota reached
500	InternalServerError	Server-side processing error	Temporary service issues

Rate Limit Handling

When you receive a 429 error, check the retryAfter header and implement exponential backoff to avoid further rate limiting.

Best Practices

Product Selection Guide

Choose the right product for your use case:

• Need raw transaction data? → Use Extract & Authenticate
• Need quick credit decisions? → Use KamoaLite or Bundle 1
• Need detailed behavioral analysis? → Use Kamoa360
• Need comprehensive assessment? → Use Bundle 2 (when available)

Phone Number Format

Always provide phone numbers in international format with country code:

+ Correct: "+254712345678"
- Incorrect: "0712345678"

Data Validation

Validate all required fields on the client side before making API calls to reduce errors and improve user experience.