Veriadd
Console

Veriadd Documentation

Everything you need to verify Nigerian addresses and cross-check identities against BVN, phone and NIN records — one API, per-call billing.

Quickstart

Provision a key and run your first verification in under 5 minutes.

Get started

API Reference

Full endpoint documentation with parameters, responses and error codes.

View API

SDKs

Native clients for JavaScript/TypeScript, Flutter, Go and Python.

Explore SDKs

Guides

Step-by-step integration guides for KYC tiers, fraud checks and webhooks.

Read guides

Authentication

All metered endpoints require an X-API-Key header containing your vr_live_... key. Public endpoints (L1 lookup, autocomplete, search) work without authentication.

auth header
http
X-API-Key: vr_live_xxxxxxxxxxxxxxxxxxxx
Note:API keys are shown once at creation time — store them in a secrets manager or environment variable immediately. Rotate compromised keys from the Console → API Keys page.

Quickstart

1. Create your account, grab an API key

Create a Veriadd account (email + password, or Google), open API Keys → Generate new key, and copy it immediately. Keys are stored hashed and never shown again.

2. Top up your wallet

L1 lookups are free. L2 (₦30) and L3 (₦50) verifications deduct from a prepaid Naira wallet. Top up from Console → Wallet via Paystack.

3. Call the API

quickstart.sh
bash
# 1. Provision a client (admin only)
curl -X POST https://api.veriadd.tech/v1/admin/clients \
  -H 'X-Admin-Key: $ADMIN_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"My Fintech","email":"api@myfintech.ng"}'
# ← { "api_key": "vr_live_..." }  (shown once)

# 2. Verify an address — L1 (free: proves the postcode exists, nothing more)
curl -X POST https://api.veriadd.tech/v1/verify/address \
  -H "X-API-Key: vr_live_..." \
  -H 'Content-Type: application/json' \
  -d '{
    "postcode": "LA-11-W06-TC-10",
    "state": "LAGOS",
    "first_name": "Adaeze",
    "last_name": "Okafor",
    "level": 1
  }'

# ← { "status": "failed", "confidence": 40,
#     "reasons": ["postcode valid in NIPOST registry (+40)", ...] }
# L1 carries no address detail, so there is nothing to match against.
# Add level 2 + identity fields for a real decision ↓

# 3. Full KYC — L3 (adds BVN + phone cross-check, ₦50)
curl -X POST https://api.veriadd.tech/v1/verify/address \
  -H "X-API-Key: vr_live_..." \
  -H 'Content-Type: application/json' \
  -d '{
    "postcode": "LA-11-W06-TC-10",
    "state": "LAGOS",
    "first_name": "Adaeze",
    "last_name": "Okafor",
    "bvn":   "22233344455",
    "phone": "08031234567",
    "level": 3
  }'
# ← { "status": "verified", "confidence": 92, "reasons": [...], "billed_ngn": 50 }
Note:The JavaScript/Python tabs use the upcoming SDK client for readability. Prefer raw HTTP (cURL tab) for production today — same endpoints, same payloads.

Response anatomy

verified response
json
{
  "data": {
    "audit_id":           "9b2ac137-f5a0-4c3d-8e6f-abcd12345678",
    "status":             "verified",      // "verified" | "partial" | "failed" | "invalid"
    "confidence":         92,             // 0–100
    "reasons": [
      "postcode valid in NIPOST registry (+40)",
      "self-reported state matches registry (+15)",
      "BVN + names match Dojah record (+10)",
      "phone identity name matches (+5)"
    ],
    "postcode_canonical": "LA-11-W06-TC-10",
    "nipost": {
      "postcode": "LA-11-W06-TC-10",
      "valid": true,
      "administrative_address": {
        "state_name": "LAGOS", "lga_name": "...",
        "locality_name": "...", "zone": "SOUTH WEST"
      },
      "recent_house_address": { "recent": "..." },
      "building_use_status": "residential"   // L3 only
    },
    "identity": {
      "provider": "dojah",
      "bvn_valid": true, "bvn_name_match": true,
      "phone_linked": true, "phone_name_match": true
    },
    "billed_kobo":        5000,
    "billed_ngn":         50
  }
}

Verification levels

LevelWhat it checksCost
L1NIPOST postcode validity only₦0 (free)
L2L1 + administrative address + BVN/phone cross-check₦30
L3L2 + building use status + full audit trail₦50

Error codes

error envelope
json
{
  "error": {
    "code":       "insufficient_credits",
    "message":    "top up your Veriadd wallet to continue",
    "request_id": "9b2ac137-..."
  }
}
CodeHTTPMeaning
missing_api_key401X-API-Key header absent
invalid_api_key401Key not found or revoked
rate_limited429Too many requests — back off and retry
insufficient_credits402Wallet balance too low — top up first
email_unverified403Verify your email first — check your inbox for the link
kyb_required403Live billable call without approved KYB — submit at Console → KYB
sandbox_not_configured503Test-key call without sandbox upstream credentials
provider_not_configured503Identity provider keys missing (Dojah)
nipost_auth502NIPOST upstream auth error
dojah_wallet502Dojah wallet insufficient — contact support

Test data

test postcodes (NIPOST)
text
LA-11-W06-TC-10   Lagos
FC-03-B06-AG-12   FCT Abuja
KN-31-F82-WJ-80   Kano
EK-01-A03-FK-01   Ekiti
OG-14-T18-BN-16   Ogun
EN-05-V19-CD-22   Enugu
test identities (Dojah sandbox)
text
bvn:   22222222222
phone: 09011111111
nin:   70123456789

# set DOJAH_BASE_URL=https://sandbox.dojah.io
# with sandbox keys to test without spending

Next steps