Introduction
Platform overview and capabilities
The UValid API provides programmatic access to Nigerian identity and business verification services. It enables banks, fintechs, embassies, and other integration partners to verify National Identification Numbers (NIN), Bank Verification Numbers (BVN), Corporate Affairs Commission (CAC) records, Tax Identification Numbers (TIN), driver licences, and phone numbers.
All endpoints are RESTful, accept JSON payloads, and return structured JSON responses. Results are permanently cached to optimise cost and latency for repeated lookups.
JWT Auth
Scoped service permissions per token
Smart Cache
Permanent response caching
Request Logging
Full audit trail for every call
Authentication
JWT Bearer tokens for all requests
All API requests must include a valid JWT Bearer token in the Authorization header. Tokens are issued by your platform administrator from the API Users dashboard.
POST https://uvalid.ng/api/client/v1/identity/nin
Authorization: Bearer <your_api_token>
Content-Type: application/json
{
"nin": "12345678901"
}Tokens are signed using HS256 and include a version number. When a token is regenerated, all previous tokens for that user are automatically invalidated.
Token Properties
| Property | Description |
|---|---|
sub | API user ID |
version | Token version (increments on regeneration) |
scope | Permitted services (wildcard * or specific keys) |
org | Organisation name |
exp | Expiration timestamp (optional) |
Response Format
Consistent JSON structure for all endpoints
{
"success": true,
"data": { ... },
"meta": {
"fromCache": false,
"timestamp": "2026-03-08T12:00:00.000Z"
}
}| Field | Type | Description |
|---|---|---|
success | boolean | Whether the request was successful |
data | object | Verification result payload |
meta.fromCache | boolean | Whether the result was served from cache |
meta.timestamp | string | ISO 8601 timestamp of the response |
Error Codes
Standard HTTP status codes with error details
{
"success": false,
"message": "Description of what went wrong"
}Invalid request payload or missing required fields
Missing, invalid, or expired API token
Account inactive or service not permitted by token scope
No record found for the provided identifier
Internal error processing the verification request
Identity Verification
Verify individuals using Nigerian national ID systems.
Phone Verification
Validate phone numbers and retrieve ownership data.
Business Verification
Look up CAC registrations and corporate data.
Compliance Verification
Tax and licence verification for regulatory compliance.
Support & Contact
Get help with integration and troubleshooting