API Documentation — Credit Veto

Overview

The CreditVeto Partners API gives approved partners programmatic access to credit scoring data for Nigerian consumers using their Bank Verification Number (BVN). All endpoints are REST-based and return JSON.

Base URLhttps://business-api-dev.creditvetoafrica.com/api/v1/scorely

Formatapplication/json

AuthX-API-Key header

Authentication

Every request must include your API key in the X-API-Key request header. You can generate and manage keys from the API Keys page.

http

GET /api/v1/scorely/credit/score?bvn=12345678901&firstName=John&lastName=Doe
Host: business-api-dev.creditvetoafrica.com/api/v1
X-API-Key: sk_sandbox_a1b2c3d4e5f6...

⚠️

Your API key carries access privileges — never expose it in client-side code, public repositories, or logs. Always make requests server-side.

Environments

CreditVeto uses the same base URL for both environments. The environment is determined entirely by the API key you use — there is no separate parameter.

Key prefix	Environment	Behaviour
sk_sandbox_…	Sandbox	Returns mock data. Safe for development and testing. No charges apply.
sk_live_…	Live	Returns real credit data. Requires an approved organisation. Counted against your monthly quota.

Get Credit Score

GET/api/v1/credit/scorecredit:read

Returns a credit score and key scoring factors for a consumer identified by their BVN.

Query parameters

Parameter	Type	Required	Description
bvn	string	Required	11-digit Bank Verification Number
firstName	string	Required	Subject's first name
lastName	string	Required	Subject's last name
email	string	Optional	Subject's email address

Example request

bash

curl -X GET \
  "https://business-api-dev.creditvetoafrica.com/api/v1/scorely/credit/score?bvn=12345678901&firstName=John&lastName=Doe" \
  -H "X-API-Key: sk_sandbox_a1b2c3d4e5f6..."

Example response — 200 OK

json

{
  "data": {
    "bvn": "12345678901",
    "score": 724,
    "scoreRange": { "min": 300, "max": 850 },
    "rating": "Good",
    "factors": [
      {
        "factor": "Bill Payment History",
        "impact": "positive",
        "description": "Consistent payment of utility bills over the last 12 months"
      },
      {
        "factor": "Payment Frequency",
        "impact": "positive",
        "description": "Regular monthly payments detected"
      },
      {
        "factor": "Account Age",
        "impact": "neutral",
        "description": "Moderate history length of 2 years"
      },
      {
        "factor": "Late Payments",
        "impact": "negative",
        "description": "2 late payments detected in the last 6 months"
      }
    ],
    "lastUpdated": "2026-03-01T00:00:00.000Z",
    "environment": "sandbox"
  }
}

Get Full Credit Report

GET/api/v1/credit/reportcredit:full_report

Returns a comprehensive credit report including personal information, bill payment history broken down by category, and a risk summary. Requires the credit:full_report scope on your API key.

Query parameters

Parameter	Type	Required	Description
bvn	string	Required	11-digit Bank Verification Number
firstName	string	Required	Subject's first name
lastName	string	Required	Subject's last name
email	string	Optional	Subject's email address

Example request

bash

curl -X GET \
  "https://business-api-dev.creditvetoafrica.com/api/v1/scorely/credit/report?bvn=12345678901&firstName=John&lastName=Doe" \
  -H "X-API-Key: sk_sandbox_a1b2c3d4e5f6..."

Example response — 200 OK

json

{
  "data": {
    "bvn": "12345678901",
    "personalInfo": {
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1990-01-15",
      "phone": "08012345678",
      "email": "[email protected]"
    },
    "creditScore": {
      "score": 724,
      "rating": "Good",
      "scoreRange": { "min": 300, "max": 850 }
    },
    "billPaymentHistory": {
      "totalBillsTracked": 48,
      "onTimePayments": 42,
      "latePayments": 4,
      "missedPayments": 2,
      "paymentRate": 87.5,
      "categories": [
        {
          "category": "Electricity",
          "provider": "Ikeja Electric",
          "totalPayments": 24,
          "onTime": 22,
          "late": 1,
          "missed": 1,
          "averageAmount": 15000
        },
        {
          "category": "Internet",
          "provider": "Spectranet",
          "totalPayments": 12,
          "onTime": 10,
          "late": 2,
          "missed": 0,
          "averageAmount": 12500
        },
        {
          "category": "Cable TV",
          "provider": "DStv",
          "totalPayments": 12,
          "onTime": 10,
          "late": 1,
          "missed": 1,
          "averageAmount": 21000
        }
      ]
    },
    "summary": {
      "accountAge": "2 years 3 months",
      "totalAmountPaid": 720000,
      "averageMonthlySpend": 48500,
      "riskLevel": "Low"
    },
    "lastUpdated": "2026-03-01T00:00:00.000Z",
    "environment": "sandbox"
  }
}

List Scored Users

GET/api/v1/credit/scored-userscredit:read

Returns a paginated list of all consumers your organisation has previously scored. Results are scoped to your organisation and optionally filtered by environment or BVN.

Query parameters

Parameter	Type	Required	Description
page	number	Optional	Page number (default: 1)
limit	number	Optional	Results per page (default: 20)
environment	sandbox \| live	Optional	Filter by environment
bvn	string	Optional	Filter by exact BVN

Example request

bash

curl -X GET \
  "https://business-api-dev.creditvetoafrica.com/api/v1/scorely/credit/scored-users?page=1&limit=20" \
  -H "X-API-Key: sk_sandbox_a1b2c3d4e5f6..."

Example response — 200 OK

json

{
  "data": {
    "users": [
      {
        "id": "uuid",
        "bvn": "12345678901",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "score": 724,
        "scoreRating": "Good",
        "environment": "sandbox",
        "createdAt": "2026-04-01T12:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "totalPages": 1
    }
  }
}

Rate Limits

Rate limits are enforced per API key on a rolling 60-second window. The current limit is included in the response headers of every request.

Header	Description
X-RateLimit-Limit	Maximum requests allowed per 60-second window for this key
X-RateLimit-Remaining	Requests remaining in the current window
Retry-After	Seconds to wait before retrying (only present on 429 responses)

When the limit is exceeded the API returns a 429 Too Many Requests response. Wait for the number of seconds in the Retry-After header before retrying.

json

{
  "statusCode": 429,
  "message": "Rate limit exceeded. Please try again later.",
  "retryAfter": 60
}

Error Reference

All errors follow a consistent shape. Check the statusCode and message fields to handle them.

json

{
  "statusCode": 401,
  "message": "Invalid or expired API key.",
  "error": "Unauthorized"
}

Status	Meaning	Common cause
401	Unauthorized	Missing, invalid, or expired X-API-Key header
401	Insufficient scopes	Your key does not have the required scope for this endpoint
403	Forbidden	Monthly request limit reached — upgrade your plan
429	Too Many Requests	Per-minute rate limit exceeded — wait and retry
500	Internal Server Error	Unexpected server error — contact support if it persists