API preview. The Verath API is in development. Endpoints, fields and behaviour shown here illustrate the planned design and may change before general availability. Sandbox credentials are issued to early partners on request.
Overview
Where Verath sits
Event sources
Verification providers
NIN/BVN lookups
Credit bureaus
Credit inquiries
Banks & fintechs
Account openings, KYC
National identity rails
Long-term goal
Verath platform
- 01Signed event gateway
- 02Keyed-hash matcher
- 03Alert engine
- 04Dispute router
Identity owner
- App push
- SMS
“Not me” → dispute back to institution
Integration steps
Live in four steps
- 01
Agree terms & receive keys
We issue a per-partner hash key, a signing secret and a client certificate for mutual TLS.
- 02
Hash at the point of lookup
When you verify a NIN or BVN, compute an HMAC of the number with your hash key. The raw number never leaves your system.
- 03
Send a signed event
POST the hash, institution, purpose, time and your reference to Verath. It doesn’t block your flow.
- 04
Receive owner responses
Subscribe to webhooks. “Not me” disputes arrive with your reference so your fraud team can act immediately.
Privacy-preserving matching
Verath never receives a list of who you checked.
You hash each identity number with a key only you and Verath hold. Verath compares the hash with its enrolled owners. No match means the event is dropped within seconds and nothing is stored. Our API response never reveals whether someone is enrolled.
Match. Alert sent to the owner; event kept in their history.
No match. Event discarded. Nothing about it is stored.
import { createHmac } from "node:crypto";
// hashKey is issued to you by Verath (one per key version).
export function identityHash(idNumber, hashKey) {
const normalized = idNumber.replace(/\D/g, ""); // 11 digits, no spaces
return createHmac("sha256", hashKey).update(normalized).digest("hex");
}Disputes
“Not me” goes straight to your fraud desk.
When an owner disputes a check, Verath sends a signed dispute.created webhook to the endpoint you register, carrying your own partner reference so you can find the application instantly.
Also available: event.confirmed when the owner confirms the check was theirs.
{
"id": "whk_01J9X…",
"type": "dispute.created",
"created_at": "2026-10-07T14:03:11+01:00",
"data": {
"event_id": "evt_8f21c0a9",
"partner_ref": "kyc-2026-10-07-55102",
"id_type": "BVN",
"purpose": "loan_application",
"owner_response": "not_me",
"dispute_id": "dsp_4c7e19"
}
}Integration security
Designed with layered controls
Per-partner keyed hashes
Each partner hashes with its own key. Keys are versioned and can be rotated.
Mutual TLS
Both sides authenticate with certificates before any event is accepted.
Signed payloads
Every request and webhook carries an HMAC signature over a timestamp and body.
Replay protection
Signatures older than the tolerance window are rejected.
Per-partner rate limits
Protects the platform and your quota from runaway clients.
Idempotent events
Retries are safe: events are de-duplicated by your partner reference.
Identity lock checks
PlannedThe same connection will be able to carry a question back: “Is this identity locked?” A locked identity asks the verifier to pause and get the owner’s approval before opening an account. It is designed to fail open, so a Verath outage never blocks banking.