Credit Risk Assessment
Upload an MPESA or bank e-statement for credit risk analysis. Send multipart/form-data with consent: true and the statement file. BANK statements also require bank_code (from GET /api/v1/credit-risk/banks) and account_number. POST is billed as credit_risk_assessment; list banks, status, and results are not billed. Poll status until completed=true, then fetch results.
Flow
- GET /api/v1/credit-risk/banks when document_type is BANK β pick a bank_code.
- POST /api/v1/credit-risk/assess as multipart/form-data β returns unique_id, document_type, and state_name.
- Poll GET /api/v1/credit-risk/status/{unique_id} until completed=true or failed=true.
- GET /api/v1/credit-risk/results/{unique_id} for normalized analysis_data, scores, and classifications.
List banks
Returns supported bank_code values for BANK statements. Auth required; not billed. Use code as bank_code on assess.
{{baseUrl}}/api/v1/credit-risk/banks{
"success": true,
"response_code": 200,
"message": "Banks fetched successfully",
"data": {
"banks": [
{ "code": "Equity", "label": "Equity Bank" },
{ "code": "KCB", "label": "Kenya Commercial Bank" },
{ "code": "NCBA", "label": "NCBA Bank" },
{ "code": "COOP", "label": "Co-operative Bank" },
{ "code": "STANBIC", "label": "Stanbic Bank" }
],
"count": 5
},
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}Assess statement
{{baseUrl}}/api/v1/credit-risk/assessHeader
Body Parameters
BANK statement
Request payload for BANK statement:
curl -X POST "{{baseUrl}}/api/v1/credit-risk/assess" \
-H "Authorization: Bearer {{token}}" \
-H "Accept: application/json" \
-F 'consent=true' \
-F 'document_type=BANK' \
-F 'bank_code=NCBA' \
-F 'account_number=0123456789' \
-F 'file=@/path/to/statement.pdf;type=application/pdf'Expected response for BANK statement:
{
"success": true,
"response_code": 200,
"message": "Credit risk assessment submitted successfully",
"data": {
"unique_id": "cra-doc-abc123",
"document_type": "BANK",
"state_name": "UPLOADED"
},
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}MPESA statement
Request payload for MPESA statement:
curl -X POST "{{baseUrl}}/api/v1/credit-risk/assess" \
-H "Authorization: Bearer {{token}}" \
-H "Accept: application/json" \
-F 'consent=true' \
-F 'document_type=MPESA' \
-F 'remote_identifier=0712345678' \
-F 'file=@/path/to/mpesa.pdf;type=application/pdf'Expected response for MPESA statement:
{
"success": true,
"response_code": 200,
"message": "Credit risk assessment submitted successfully",
"data": {
"unique_id": "cra-doc-mpesa-456",
"document_type": "MPESA",
"state_name": "UPLOADED"
},
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}Response Fields
Document types
Poll status
Use unique_id from POST. Not billed. Keep polling while completed=false and failed=false. Terminal failure states include FRAUDULENT, ERROR, and REJECTED.
{{baseUrl}}/api/v1/credit-risk/status/{unique_id}In progress
{
"success": true,
"response_code": 200,
"message": "Analysis in progress",
"data": {
"unique_id": "cra-doc-abc123",
"document_type": "BANK",
"state_name": "UPLOADED",
"completed": false,
"failed": false
},
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}Complete
{
"success": true,
"response_code": 200,
"message": "Analysis complete",
"data": {
"unique_id": "cra-doc-abc123",
"document_type": "BANK",
"state_name": "COMPLETED",
"completed": true,
"failed": false
},
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}Failed
{
"success": true,
"response_code": 200,
"message": "Assessment failed",
"data": {
"unique_id": "cra-doc-abc123",
"document_type": "BANK",
"state_name": "REJECTED",
"completed": false,
"failed": true
},
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}Fetch results
Returns normalized analysis_data (BANK flat payloads are promoted into the same last_data shape as MPESA), scores, and classifications. Returns HTTP 409 if the assessment is not complete yet.
{{baseUrl}}/api/v1/credit-risk/results/{unique_id}{
"success": true,
"response_code": 200,
"message": "Credit risk results fetched successfully",
"data": {
"unique_id": "cra-doc-abc123",
"document_type": "BANK",
"state_name": "COMPLETED",
"account_number": "0123456789",
"bank_name": "NCBA",
"phone": null,
"scores": {
"score": 642,
"risk_level": "Moderate",
"affordability": 18500,
"highest_saf_loan": 12000,
"highest_other_loan": 8000,
"score_reason_summary": "Stable inflows with moderate expense pressure"
},
"classifications": [
{
"name": "Salary",
"received": { "total": 85000, "count": 1, "highest": 85000, "lowest": 85000 },
"sent": { "total": 0, "count": 0 }
},
{
"name": "Transfers",
"received": { "total": 12000, "count": 3, "highest": 5000, "lowest": 2000 },
"sent": { "total": 22000, "count": 5, "highest": 8000, "lowest": 500 }
}
],
"analysis_data": {
"DocType": "BANK",
"last_data": {
"header": {
"opening_balance": 21450.5,
"closing_balance": 31890.25,
"total_paid_in": 97000,
"total_paid_out": 86560.25
},
"information": {
"customer_names": "JANE SAMPLE",
"bank_name": "NCBA",
"bank_account": "0123456789",
"statement_period": "2026-01-01 - 2026-03-31"
},
"body": {
"locations": [],
"monthly_inflow": {},
"monthly_outflow": {}
},
"end_of_day_balances": []
}
},
"processed_at": "2026-11-10T12:45:00Z"
},
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}Error codes
Standard Peleza HTTP / response_code values (same across all API calls). Validation message text is endpoint-specific. Full reference: Error Codes.
Set {{baseUrl}} to https://api.peleza.com (production) or https://sandbox.peleza.com (sandbox). Authenticated calls need a Bearer token from POST /api/v1/oauth/token.
