API Documentation

Authentication

Two methods are supported. Use Authorization: Bearer for dashboard and account calls, and X-API-Key for programmatic calls from your servers.

Bearer token

Authorization: Bearer <session_token>

API key

X-API-Key: idn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep keys on the server. A key spends your credit balance. Never put one in client-side code, a public repository or a shared document. API keys require KYC Level 3 (biometric verification) before you can generate them. Keys issued before the IDNexus rename start with bk_live_ and keep working.

Verification endpoints

Each call deducts credits from your balance. If the balance is too low the call returns 402 and nothing is processed. Requests with a missing or invalid image are rejected before any charge, and a call that fails upstream is refunded automatically. Images must be JPEG, PNG or WebP, up to 8 MB each.

Basic verification 10 credits

POST/api/v1/v1/verify/basic

Liveness detection on a selfie. Returns an accept or reject decision.

curl -X POST https://verify.skillnexus.uk/api/v1/v1/verify/basic \
  -H "X-API-Key: idn_live_..." \
  -F "selfie=@selfie.jpg"

Standard verification 50 credits

POST/api/v1/v1/verify/standard

Liveness, OCR and face match. Requires a selfie and a document (passport, ID card or driver's licence).

curl -X POST https://verify.skillnexus.uk/api/v1/v1/verify/standard \
  -H "X-API-Key: idn_live_..." \
  -F "selfie=@selfie.jpg" \
  -F "document=@passport.jpg" \
  -F "full_name=John Doe"

Enterprise verification 100 credits

POST/api/v1/v1/verify/enterprise

Adds deepfake detection on top of Standard. The response includes deepfake.model and deepfake.passed.

Identity lookup

Look up BVN, NIN or phone attributes. Results are billed at the rates published on GET /identity/pricing. You must have the individual's consent before every lookup.

BVN lookup

POST/api/v1/identity/bvn

curl -X POST https://verify.skillnexus.uk/api/v1/identity/bvn \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"bvn": "22223333444", "slip_type": "standard"}'

NIN lookup

POST/api/v1/identity/nin

curl -X POST https://verify.skillnexus.uk/api/v1/identity/nin \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"nin": "12345678901", "version": "v1", "slip_type": "standard"}'

Use version: "v2" for strict non-refundable mode.

Phone lookup

POST/api/v1/identity/phone

Billing

Get balance

GET/api/v1/billing/balance

{
  "balance_cents": 5000,
  "balance_usd": "50.00"
}

Start a top-up

POST/api/v1/billing/topup

{
  "amount_usd": 25,
  "provider": "paystack"
}

Returns {"checkout_url": "..."}. Redirect the user to that URL to pay.

Usage

GET/api/v1/usage/summary

{
  "month": {
    "basic": 42,
    "standard": 18,
    "enterprise": 5,
    "identity": 12,
    "credits": 1350
  }
}

Error codes

Status	Meaning
`401` Unauthorized	Missing or invalid credentials
`402` Payment Required	Insufficient credits
`403` Forbidden	KYC level insufficient
`404` Not Found	Endpoint or resource missing
`409` Conflict	Duplicate email or phone
`429` Too Many Requests	Rate limit exceeded; wait for the `Retry-After` seconds
`413` / `422`	Upload too large (8 MB per image), or the image could not be verified. Credits are refunded.
`500` Internal Error	Server-side failure

All errors return JSON with an error field:

{"error": "insufficient_credits", "required_cents": 50, "balance_cents": 30}