Identity Resolution Overview
Country-pluggable identity resolver with per-(country, provider) circuit breakers, latency tracking, and a dead-letter queue.
The PlatformXe Identity Resolution Service is a country-pluggable resolver: a single API surface dispatches identifier lookups through the right per-country provider chain. Phase 6F.5 introduced country plugins as drop-in modules; Phase 6F.5b added latency observations, hedging, and a dead-letter queue. Phase 6F shipped per-kind verifications (BVN, NIN, liveness, face-match, account-name) with KMS-encrypted audit persistence.
Supported countries
| Code | Country | Identifier types | Capabilities |
|---|---|---|---|
NG | Nigeria | BVN, NIN, TIN, PASSPORT, PHONE, VOTER_ID, DRIVERS_LICENSE | BVN, NIN, liveness, face-match, account |
KE | Kenya | NIN (Huduma Number), TIN (KRA PIN), PASSPORT, PHONE, DRIVERS_LICENSE | NIN, liveness, face-match |
GH | Ghana | NIN (Ghana Card), TIN, PASSPORT, PHONE, VOTER_ID, DRIVERS_LICENSE | NIN, liveness, face-match, account |
ZA | South Africa | NIN (SAID), TIN (SARS), PASSPORT, PHONE, DRIVERS_LICENSE | NIN, liveness, face-match, account |
NIN is the canonical key for each country's primary national identifier; the country plugin handles validation against local format (8-digit Huduma vs GHA-XXXXXXXXX-X Ghana Card vs 13-digit SAID). BVN stays Nigeria-specific. See Identity Resilience for the per-country provider chains, breaker state, and replay flow.
Nigerian identifier types (default)
| Type | Code | Description |
|---|---|---|
| Bank Verification Number | bvn | 11-digit BVN issued by NIBSS |
| National Identification Number | nin | 11-digit NIN issued by NIMC |
| Tax Identification Number | tin | TIN issued by FIRS |
| Voter Card | voter | Permanent Voter Card number (INEC) |
| International Passport | passport | Nigerian passport number |
| Phone Number | phone | Mobile number linked to identity records |
| Driver's License | license | National driver's license number (FRSC) |
How it works
NIN serves as the resolution hub. When you submit any identifier type, the service resolves it through the provider chain and links it back to the NIN, then resolves other linked identifiers from there.
Input (BVN) → Provider Chain → NIN (hub) → Linked identifiers (TIN, Voter, Passport, etc.)
The service queries each country's declared provider chain in priority order, returning the first successful match. Each (country, provider) pair has its own circuit breaker — a flaky provider in one country quarantines without dragging down others. Combined, the provider network covers over 130 million identity records across the supported countries.
Caching
Resolved identities are cached in Redis with a 24-hour TTL. Subsequent lookups for the same identifier hit the cache instead of making provider calls, reducing latency and cost.
No personally identifiable information (PII) is persisted to the database. The Redis cache is the only storage, and entries expire automatically after 24 hours.
Consent requirement
Every identity resolution request must include a consent reference. PlatformXe is a pass-through service — your application is responsible for obtaining consent from the data subject before calling the API.
See Consent & NDPR for full details on compliance requirements.
API scope
All identity resolution endpoints require the identity:resolve scope on your API key.
Next steps
- Resolve Identity — API reference for the resolve endpoint
- Per-kind verification endpoints — BVN, NIN, liveness, face-match, account-name
- Identity Resilience — country plugins, per-(country, provider) circuit breakers, latency surface, dead-letter queue, hedging
- Consent & NDPR — compliance requirements for identity lookups