Documentation

Full API reference

This is the fully custom path, you build the verification screens yourself and call these endpoints directly from your backend. Every endpoint here needs the signed headers from Authentication plus a bearer access token, unless noted otherwise. If you'd rather not build a UI at all, see Hosted Verification instead, it covers the same ID-number checks with far less code.

Quick Verify; one call, one answer

For when you just need to know if a set of IDs check out, with nothing to poll and nothing to look up later. Document and facial checks aren't available here, those need the async flow further down.

Response: data:

{
  "session_id": "8c37ef2e-017b-4cf6-8882-c1b39c4495fe",
  "outcome": "approved",
  "reference": "order-42",
  "verified_at": "2026-01-01T12:00:00Z",
  "overall_confidence": 96,
  "checks": {
    "nin": {
      "status": "passed",
      "confidence": 96,
      "matched_name": "Ada Okafor",
      "cost": 200,
      "wallet_balance_after": 48800,
      "history_ulid": "01J..."
    }
  }
}

BVN; richer than a plain lookup

A bvn check pulls the full holder profile (watch_listed, enrollment_bank, enrollment_branch, level_of_account, email, title, marital_status, state/LGA of origin and residence) in every response. Two things layer on top of that, each independently optional:

• Send first_name/last_name/date_of_birth and the response includes match_confidence ; a per-field { confidence_value, status } breakdown for bvn, first_name, and last_name, straight from the registry, not a guess on our side.
• Send bvn_selfie_image and the response includes selfie_match : { confidence_value, match } , confirming the selfie belongs to the BVN holder.

Either extra costs a bit more than a bare lookup (each is a separate check behind the scenes), but the price you're charged is still the one flat bvn rate from GET /wallet ; no surprise line items.

Credit Bureau

A credit_bureau check is looked up by bvn and returns a score object; loan counts, active/closed loans, and other metrics, each broken out per bureau source (e.g. [{ "source": "CRC", "value": 3 }, { "source": "FIRST_CENTRAL", "value": 1 }] rather than one blended number). Unlike every other check type, this one is never served from cache, credit standing changes, so it's always a fresh pull and always fully billed.

Verification sessions, the full onboarding flow

Use this when you need document upload and/or facial liveness, or when you want a persistent record you can look up later (a subject applying for a loan, a tenant onboarding, etc).

1. Create a subject (optional but recommended)

A subject is the person being verified. Reuse the same subject across multiple verification sessions instead of re-entering their details each time.

• GET /subjects : list yours, filterable by kyc_status, is_flagged, or q (search).
• GET /subjects/{ulid} · PATCH /subjects/{ulid}; read or update one.
• GET /subjects/{ulid}/sessions : every verification session run against them.

2. Start a verification session

The response includes next_steps , a map of which endpoint to call for each pending check, so you don't have to hardcode the URL shape yourself.

3a. ID-number step, NIN and BVN are separate endpoints

If required_checks includes both, submit to both paths below, there's no single generic endpoint that takes either id type. Call whichever of the two your session actually requires.

3b. Document upload step

Documents upload directly to encrypted storage, your server never proxies the file bytes.

3c. Facial liveness step

4. Read the final results

• GET /verifications; list your sessions.
• GET /verifications/{ulid} ; status summary (which checks are pending/completed/failed).
• DELETE /verifications/{ulid} ; cancel a session that hasn't completed yet.

Face Collections; 1:N biometric login

A different shape of problem from the sessions above: instead of a one-shot "does this selfie match this document," a collection lets you enroll a face once and then re-authenticate that same person on every later visit; biometric login, not a one-time onboarding check. A collection persists across as many verification sessions as you need.

Create and manage a collection

• GET /face-collections : list yours.
• GET /face-collections/{ulid} · DELETE /face-collections/{ulid}
• GET /face-collections/{ulid}/faces : everyone currently enrolled.

Enroll a face

Authenticate (1:1) and Search (1:N)

These are the re-verification moment, and both go through the same two-step check server-side before you get a result: a passive liveness/anti-spoofing pass first, then the identity match, a non-live selfie never reaches the match step, so you're not billed for comparing a photo of a photo against your collection.

Face ↔ Document Compare

A stateless one-shot compare, no enrollment, nothing persisted on either side, for confirming a selfie matches the photo on an ID document image. Use this instead of Face Collections when there's no ongoing relationship to set up, just a single "is this the same person" check.

Verification history

Every ID you've successfully looked up (via any method) is queryable later, useful for an audit trail without you having to build your own database of results.

• GET /verifications/history ; filter by check_type or source.
• GET /verifications/history/{ulid} ; one record in full.

Phone number verification

A standalone OTP check, independent of the session flow above.

• POST /phone/verify : { "phone": "0801..." }, sends an SMS code.
• POST /phone/verify/confirm : { "reference", "otp" }.
• GET /phone/verify/status/{reference}

Wallet

• GET /wallet : current balance and per-check pricing.
• GET /wallet/transactions ; full ledger.
• POST /wallet/fund/initialize : { "amount", "callback_url" }, returns a Paystack checkout URL.
• GET /wallet/fund/verify/{reference} : confirm a top-up after the Paystack redirect.

Public ID search, no auth required

A separate, fully unauthenticated pair of endpoints; no client_key needed at all. This is what powers the public Search an ID page: free if the record is already cached, otherwise a small Paystack charge before a fresh lookup.

Rate limits