API reference

Integrate credit scoring into your platform

The AfriScore API accepts alternative data fields and returns a calibrated credit score, risk tier, and probability of default. A slower endpoint adds SHAP-based explainability on request.

01

Quickstart

Your first API call, illustrated below. Live keys are issued after pilot onboarding.

Send your key as a Bearer token in the Authorization header. Without a key you use the anonymous tier, which has strict limits.

Monthly mobile money volume, average airtime top-up, device instability, loan amount and loan term are optional. A left-out field is scored at a typical value and listed in assumed_inputs and warnings. Send every field you have: a score that rests on assumed values describes a typical applicant, not yours.

curl -X POST https://api.afriscore.africa/v1/score \
  -H "Authorization: Bearer YOUR_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "momo_txn_count_monthly": 38,
    "momo_txn_volume_monthly_xaf": 145000,
    "momo_account_age_months": 18,
    "momo_balance_volatility": 0.35,
    "momo_inflow_outflow_ratio": 1.12,
    "airtime_topup_freq_monthly": 6,
    "airtime_topup_regularity": 0.82,
    "airtime_avg_topup_xaf": 800,
    "device_age_months": 14,
    "device_os_updated": true,
    "device_instability_score": 0.2,
    "has_prior_mfi_loan": false,
    "prior_loan_repaid_on_time_ratio": -1,
    "loan_amount_xaf": 80000,
    "loan_term_months": 3
  }'
02

Endpoints

POST

/v1/score

Submit an application for scoring. Returns score, risk tier, and probability of default — fast, well under a second.

200 OK
{
  "score": 748,
  "risk_tier": "C",
  "probability_of_default": 0.185,
  "reasons": [
    {
      "code": "AIRTIME_TOPUP_REGULARITY_RISK_DOWN",
      "feature": "airtime_topup_regularity",
      "impact": "favourable",
      "text": "Airtime top-up regularity (0.82) pulled the estimated risk down."
    },
    {
      "code": "MOMO_ACCOUNT_AGE_MONTHS_RISK_UP",
      "feature": "momo_account_age_months",
      "impact": "adverse",
      "text": "Mobile money account age (18 months) pushed the estimated risk up."
    },
    {
      "code": "MOMO_TXN_VOLUME_MONTHLY_XAF_RISK_UP",
      "feature": "momo_txn_volume_monthly_xaf",
      "impact": "adverse",
      "text": "Monthly mobile money volume (145,000 XAF) pushed the estimated risk up."
    },
    {
      "code": "DEVICE_INSTABILITY_SCORE_RISK_DOWN",
      "feature": "device_instability_score",
      "impact": "favourable",
      "text": "Device instability (0.2) pulled the estimated risk down."
    }
  ],
  "model_version": "0.3.0"
}
POST

/v1/explain

Same result as /v1/score, plus SHAP-based feature contributions explaining the decision. Significantly slower — roughly 15-25 seconds per request.

200 OK
{
  "score": 748,
  "risk_tier": "C",
  "probability_of_default": 0.185,
  "top_factors": [
    {
      "feature": "airtime_topup_regularity",
      "value": 0.82,
      "shap_contribution": -0.0479,
      "direction": "decreased"
    },
    {
      "feature": "momo_account_age_months",
      "value": 18,
      "shap_contribution": 0.0319,
      "direction": "increased"
    },
    {
      "feature": "momo_txn_volume_monthly_xaf",
      "value": 145000,
      "shap_contribution": 0.0221,
      "direction": "increased"
    }
  ],
  "reasons": [
    {
      "code": "AIRTIME_TOPUP_REGULARITY_RISK_DOWN",
      "feature": "airtime_topup_regularity",
      "impact": "favourable",
      "text": "Airtime top-up regularity (0.82) pulled the estimated risk down."
    }
  ],
  "counterfactuals": {
    "current_score": 748,
    "current_tier": "C",
    "target_tier": "B",
    "target_score": 777,
    "changes": [
      {
        "feature": "device_instability_score",
        "current": 0.2,
        "suggested": 0.1637,
        "new_score": 777,
        "new_tier": "B",
        "reaches_target_tier": true
      },
      {
        "feature": "airtime_topup_regularity",
        "current": 0.82,
        "suggested": 0.9159,
        "new_score": 777,
        "new_tier": "B",
        "reaches_target_tier": true
      }
    ]
  },
  "model_version": "0.3.0"
}
GET

/v1/health

Check API status. No authentication required.

200 OK
{
  "status": "ok",
  "version": "0.4.0",
  "model_version": "0.3.0"
}
03

Try It

This calls the live AfriScore API directly from your browser. The model is trained on synthetic data — real institutional calibration happens during a pilot.

Request

Response

{ }

This calls the live early-stage API at https://api.afriscore.africa, anonymously, so strict limits apply (10 scores and 3 explanations a minute). The model is trained on synthetic data. Real institutional calibration happens during a pilot. Request a test key for higher limits.

Full Documentation

Authentication, error codes, rate limits and integration guides.

Everything you need to integrate AfriScore into your loan origination system: API keys, rate limits, error handling and the full request and response reference.