Peleza β€” Trust built on data
πŸ‡°πŸ‡ͺ Credit Risk
On this page

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.

GET/api/v1/credit-risk/banks
{{baseUrl}}/api/v1/credit-risk/banks
200 OKSample dataExpected response
{
  "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"
}
FieldTypeDescription
data.banksarrayOrdered list of { code, label }
data.banks[].codestringValue to send as bank_code
data.banks[].labelstringDisplay name
data.countintegerNumber of banks returned

Assess statement

POST/api/v1/credit-risk/assess
{{baseUrl}}/api/v1/credit-risk/assess
HeaderTypeDescription
AuthorizationstringBearer YOUR_ACCESS_TOKEN from the OAuth client-credentials flow
Content-Typestringmultipart/form-data (set automatically by your HTTP client when attaching files)
Acceptstringapplication/json

Body Parameters

ParameterTypeDescriptionRequired
document_typestringMPESA or BANKrequired
filefileStatement file β€” PDF, CSV, XLSX, or XLS (max 10 MB). Also accepts file[].required
bank_codestringRequired for BANK β€” bank code from GET /api/v1/credit-risk/banks (e.g. NCBA, KCB, Equity)conditional
account_numberstringRequired for BANK β€” account number (min 3 characters)conditional
remote_identifierstringOptional subject reference. Alias: number. Defaults to account_number for BANK.optional
decrypterstringOptional password / decrypt key when the statement PDF is encryptedoptional
consentbooleanMust be true β€” confirms data-subject consent to perform this verificationrequired

BANK statement

Request payload for BANK statement:

Sample dataRequest payload
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:

200 OKSample dataExpected response
{
  "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:

Sample dataRequest payload
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:

200 OKSample dataExpected response
{
  "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

FieldTypeDescription
successbooleanWhether the request succeeded
response_codenumberApplication response code (typically mirrors HTTP)
messagestringHuman-readable status message
dataobjectPayload for the verified resource
request_idstringUUID for support and audit trails
data.unique_idstringDocument unique id β€” use when polling status and fetching results
data.document_typestringMPESA or BANK
data.state_namestringUPLOADED | DUPLICATE | COMPLETED | …

Document types

ValueMeaning
MPESAM-PESA statement (PDF/CSV/Excel). bank_code and account_number are not required.
BANKBank e-statement. Requires bank_code + account_number (min 3 chars).

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.

GET/api/v1/credit-risk/status/{unique_id}
{{baseUrl}}/api/v1/credit-risk/status/{unique_id}

In progress

200 OKSample dataExpected response
{
  "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

200 OKSample dataExpected response
{
  "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

200 OKSample dataExpected response
{
  "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"
}
FieldTypeDescription
data.unique_idstringDocument unique id from assess
data.document_typestringMPESA or BANK
data.state_namestringCurrent processing state
data.completedbooleantrue when analysis is ready
data.failedbooleantrue on terminal failure

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.

GET/api/v1/credit-risk/results/{unique_id}
{{baseUrl}}/api/v1/credit-risk/results/{unique_id}
200 OKSample dataExpected response
{
  "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"
}
FieldTypeDescription
data.unique_idstringDocument unique id from assess
data.document_typestringMPESA or BANK
data.state_namestringUsually COMPLETED
data.account_numberstringBANK account when provided
data.bank_namestringBANK code / name when provided
data.phonestringMPESA remote identifier when provided
data.scoresobjectscore, risk_level, affordability, loan signals, reason summary
data.classificationsarrayMerged inflow/outflow classification buckets
data.analysis_dataobjectNormalized analysis payload (includes last_data for BANK and MPESA)
data.processed_atstringCompletion timestamp when available

Error codes

Standard Peleza HTTP / response_code values (same across all API calls). Validation message text is endpoint-specific. Full reference: Error Codes.

CodeWhenBilled?
200Assessment accepted (or already completed for a duplicate) β€” billed as credit_risk_assessmentYes
401Missing or invalid Bearer tokenNo
402Insufficient wallet balance or credit limitNo
403No active wallet / billing profile, or service not enabledNo
422Validation failed (consent, document_type, file, BANK bank_code/account_number) or provider rejected the uploadNo
502Provider upload failedNo
503Credit risk assessment is not configuredNo

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.