Public API Reference

Overview

The Kredete Public API provides programmatic access to all credit management functionality. The API follows RESTful principles with JSON request/response payloads and uses OAuth 2.0 for authentication.

Base URLs

Authentication

OAuth 2.0 Client Credentials Flow

# Request access token
curl -X POST https://api.kredete.com/v2/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=read:customers write:loans"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:customers write:loans"
}

Using the Access Token

curl -X GET https://api.kredete.com/v2/customers \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

API Rate Limits

Rate Limit Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1713254460

Customer Management

Create Customer

POST /v2/customers

Request Body:

{
  "first_name": "Adewale",
  "last_name": "Okonkwo",
  "email": "adewale.okonkwo@email.com",
  "phone": "+2348012345678",
  "date_of_birth": "1990-05-15",
  "gender": "male",
  "nationality": "NG",
  "identification": {
    "type": "NIN",
    "number": "12345678901",
    "expiry_date": "2030-12-31"
  },
  "address": {
    "street": "15 Victoria Island",
    "city": "Lagos",
    "state": "Lagos",
    "country": "NG",
    "postal_code": "101233"
  },
  "employment": {
    "status": "employed",
    "employer": "ABC Company Ltd",
    "job_title": "Software Engineer",
    "monthly_income": 850000,
    "employment_date": "2018-03-01"
  }
}

Response (201 Created):

{
  "id": "cust_2xK9mN3pQ7vR",
  "external_id": null,
  "first_name": "Adewale",
  "last_name": "Okonkwo",
  "email": "adewale.okonkwo@email.com",
  "phone": "+2348012345678",
  "status": "pending_kyc",
  "kyc_status": "not_started",
  "created_at": "2026-04-16T10:30:00Z",
  "updated_at": "2026-04-16T10:30:00Z"
}

Get Customer

GET /v2/customers/{customer_id}

List Customers

GET /v2/customers?status=active&page=1&limit=20

Loan Management

Create Loan Application

POST /v2/loans

{
  "customer_id": "cust_2xK9mN3pQ7vR",
  "product_id": "prod_personal_loan",
  "amount": 500000,
  "currency": "NGN",
  "tenure_days": 90,
  "purpose": "business_expansion",
  "disbursement_account": {
    "bank_code": "058",
    "account_number": "1234567890",
    "account_name": "Adewale Okonkwo"
  }
}

Response:

{
  "id": "loan_5tY8kL2mN9pQ",
  "customer_id": "cust_2xK9mN3pQ7vR",
  "product_id": "prod_personal_loan",
  "amount": 500000,
  "currency": "NGN",
  "tenure_days": 90,
  "interest_rate": 2.5,
  "total_interest": 37500,
  "total_repayment": 537500,
  "monthly_payment": 179167,
  "status": "pending_review",
  "created_at": "2026-04-16T11:00:00Z"
}

Approve Loan

POST /v2/loans/{loan_id}/approve

Reject Loan

POST /v2/loans/{loan_id}/reject

Disburse Loan

POST /v2/loans/{loan_id}/disburse

Payment Management

Record Payment

POST /v2/payments

{
  "loan_id": "loan_5tY8kL2mN9pQ",
  "amount": 179167,
  "currency": "NGN",
  "payment_method": "bank_transfer",
  "payment_reference": "TRF-20260516-001",
  "payment_date": "2026-05-16"
}

Response:

{
  "id": "pmt_7rU2kM8nP4qS",
  "loan_id": "loan_5tY8kL2mN9pQ",
  "customer_id": "cust_2xK9mN3pQ7vR",
  "amount": 179167,
  "currency": "NGN",
  "allocation": {
    "principal": 166667,
    "interest": 12500,
    "fees": 0,
    "penalties": 0
  },
  "status": "completed",
  "created_at": "2026-05-16T10:30:00Z"
}

Credit Scoring

Request Credit Score

POST /v2/scoring/score

{
  "customer_id": "cust_2xK9mN3pQ7vR",
  "score_type": "full",
  "data_sources": ["bureau", "internal", "alternative"],
  "loan_amount": 500000,
  "loan_tenure_days": 90
}

Response:

{
  "id": "score_3wE5jK9lM2nQ",
  "customer_id": "cust_2xK9mN3pQ7vR",
  "score": 720,
  "score_band": "good",
  "risk_category": "low",
  "probability_of_default": 0.03,
  "recommended_limit": 750000,
  "recommended_tenure_max": 180,
  "factors": [
    {
      "factor": "payment_history",
      "impact": "positive",
      "description": "Excellent payment history on previous loans"
    },
    {
      "factor": "credit_utilization",
      "impact": "neutral",
      "description": "Moderate credit utilization"
    }
  ],
  "valid_until": "2026-04-23T10:30:00Z",
  "created_at": "2026-04-16T10:30:00Z"
}

Webhooks / Notifications

Configure Webhook

POST /v2/webhooks

{
  "url": "https://your-server.com/webhooks/kredete",
  "events": [
    "loan.created",
    "loan.approved",
    "loan.disbursed",
    "loan.repayment",
    "customer.kyc_verified",
    "payment.received"
  ],
  "secret": "your-webhook-secret",
  "active": true
}

Webhook Payload Example

{
  "id": "evt_2xK9mN3pQ7vR",
  "type": "loan.disbursed",
  "created_at": "2026-04-17T09:00:00Z",
  "data": {
    "loan_id": "loan_5tY8kL2mN9pQ",
    "customer_id": "cust_2xK9mN3pQ7vR",
    "amount": 500000,
    "currency": "NGN",
    "disbursement_reference": "DISB-2026041700001"
  }
}

Webhook Signature Verification

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Error Handling

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "amount",
        "message": "Amount must be greater than minimum loan amount of 10000"
      }
    ],
    "request_id": "req_3wE5jK9lM2nQ"
  }
}

Error Codes

SDK Libraries