AfriScore Documentation

Overview

AfriScore transforms mobile money transaction data, airtime purchase patterns, and device metadata into explainable credit decisions. This documentation covers the full request/response lifecycle.

Authentication

All API requests require a valid API key passed as a Bearer token in the Authorization header. Keys are issued after pilot onboarding.

Authorization: Bearer afriscore_live_xxxxxxxxxxxxxxxxxxxxxxxx

Quickstart

Score a hypothetical applicant with 18 months of mobile money history using the example below.

export AFRISCORE_API_KEY=afriscore_test_xxxxxxxx

curl -X POST https://api.afriscore.dev/v1/score \
  -H "Authorization: Bearer $AFRISCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mm_months": 18,
    "avg_inflow": 1200,
    "avg_outflow": 950,
    "avg_balance": 450,
    "balance_stability": 0.65,
    "counterparties": 12,
    "tx_frequency": 38,
    "weekend_activity": 0.28,
    "airtime_avg": 8,
    "airtime_freq": 6,
    "airtime_regularity": 0.82,
    "device_type": "smartphone",
    "device_age_months": 14,
    "requested_amount": 300,
    "requested_term_days": 90,
    "loan_purpose": "business",
    "region": "central_africa"
  }'

POST /v1/score

Submit an application for credit scoring. Returns a complete assessment including score, tier, recommendation, and SHAP feature contributions.

Request Fields

{
  "score": 742,
  "tier": "A",
  "default_probability": 0.02,
  "decision": "APPROVED",
  "recommended_limit": 5000,
  "recommended_term_days": 365,
  "recommended_apr": 12.0,
  "shap_values": [
    { "feature": "balance_stability", "contribution": 0.18 },
    { "feature": "avg_inflow", "contribution": 0.15 }
  ],
  "request_id": "req_abc123",
  "processing_ms": 187
}

POST /v1/explain

Returns SHAP values and counterfactual explanations without storing the request. Useful for borrower-facing explainability screens.

{
  "shap_values": [ ... ],
  "counterfactuals": [
    {
      "feature": "balance_stability",
      "current_value": 0.45,
      "target_value": 0.60,
      "score_gain": 32
    }
  ]
}

GET /v1/health

Check API status. No authentication required.

{
  "status": "healthy",
  "version": "1.1.0",
  "uptime_seconds": 2592000
}

Docker Deployment

The engine is designed to be fully containerized for institutions with data residency requirements.

docker pull ghcr.io/charlesmfouapon/afriscore-engine:latest

docker run -d -p 8080:8080 \
  -e AFRISCORE_API_KEY=your_key \
  -e MODEL_PATH=/app/models/ensemble.pkl \
  ghcr.io/charlesmfouapon/afriscore-engine:latest

SHAP Values

AfriScore uses Kernel SHAP to explain every credit decision. Each feature receives a contribution score — positive values increase the final score, negative values decrease it. This enables auditability for both lenders and borrowers.

Counterfactual Explanations

Counterfactuals show what a borrower would need to change to improve their score — for example, what increasing balance stability from 0.45 to 0.60 would do to the outcome.

SDKs & Libraries

Python and JavaScript client libraries are planned once the first pilot integration is live.

Source Code

The scoring engine, model card, and stress testing suite will be made available on GitHub as the project matures.