Verify an identity using an 11-digit NIN.
Verify an identity record using an 11-digit NIN.
POST /v1/verifications/nin
| Property | Value |
|---|---|
| Scope | NIN_VERIFY |
| Live price | ₦100 |
| Test charge | ₦0 |
| Idempotency-Key | Required |
Checkdata.status
SUCCESSFUL,NOT_FOUND, andSUSPENDEDare completed outcomes. They all return HTTP200and live requests are charged.
Headers
Authorization: Bearer id_test_your_key
Idempotency-Key: req_550e8400-e29b-41d4-a716-446655440000
Content-Type: application/jsonRequest body
| Field | Type | Required | Description |
|---|---|---|---|
nin | string | Yes | Exactly 11 digits. |
{
"nin": "12345678901"
}cURL example
curl -X POST "https://api.idyntic.getapexly.com/v1/verifications/nin" \
-H "Authorization: Bearer id_test_your_key" \
-H "Idempotency-Key: req_550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{"nin":"12345678901"}'HTTP 200: successful verification
The object inside nin_data contains the complete verification data for this endpoint. Empty strings and null values are intentionally preserved.
{
"success": true,
"message": "NIN Verification (NIN) Successful",
"data": {
"reference": "550e8400-e29b-41d4-a716-446655440001",
"status": "SUCCESSFUL",
"type": "nin",
"environment": "live",
"nin_data": {
"gender": "FEMALE",
"nin_suspension_status": false,
"photo": "/9j/4AAQSkZJRgABAQAAAQABAAD/2Q==",
"firstname": "CHIDINMA",
"middlename": "ADAEZE",
"nin_suspension_message": "NOT SUSPENDED",
"surname": "NWACHUKWU",
"birthdate": "05-12-1994",
"nin": "12345678901",
"telephoneno": "",
"residence_address": "24 SPECIMEN AVENUE, OFF DEMO ROAD"
}
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": true,
"note": "Wallet charged 100.00 NGN"
}
}The sample photo value is a shortened dummy JPEG Base64 value. Live responses contain the complete Base64-encoded image.
HTTP 200: record not found
{
"success": true,
"message": "Record not found",
"data": {
"reference": "550e8400-e29b-41d4-a716-446655440002",
"status": "NOT_FOUND",
"type": "nin",
"environment": "live",
"nin_data": null
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": true,
"note": "Wallet charged 100.00 NGN"
}
}HTTP 200: NIN suspended
{
"success": true,
"message": "This NIN is suspended by NIMC.",
"data": {
"reference": "550e8400-e29b-41d4-a716-446655440003",
"status": "SUSPENDED",
"type": "nin",
"environment": "live",
"nin_data": null
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": true,
"note": "Wallet charged 100.00 NGN"
}
}A restricted outcome may include verification data. When it is unavailable, nin_data is null.
Error responses
| HTTP | Code | When it happens |
|---|---|---|
400 | INVALID_REQUEST | NIN must be 11 digits |
400 | INVALID_IDEMPOTENCY_KEY | Header is missing or does not match the required format |
401 | UNAUTHORIZED | Key is invalid, expired, revoked, or lacks NIN_VERIFY |
402 | INSUFFICIENT_BALANCE | Live wallet balance is below ₦100 |
409 | IDEMPOTENCY_KEY_REUSED | The key was used with a different request body |
409 | IDEMPOTENCY_IN_PROGRESS | The same live operation is still processing |
429 | RATE_LIMIT_EXCEEDED | Per-key request limit was exceeded |
500 | INTERNAL_ERROR | An unexpected error prevented completion |
503 | SERVICE_UNAVAILABLE | The verification service is temporarily unavailable |
Invalid request example
{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "NIN must be 11 digits",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": false,
"note": "No charges"
}
}Insufficient balance example
{
"success": false,
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "Your wallet balance is insufficient for this verification.",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": false,
"note": "No charges"
}
}Idempotency conflict example
{
"success": false,
"error": {
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "This Idempotency-Key was already used with a different request.",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": false,
"note": "No charges"
}
}Service unavailable example
{
"success": false,
"error": {
"code": "SERVICE_UNAVAILABLE",
"message": "Verification service is temporarily unavailable, try again later.",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": false,
"note": "No charges"
}
}All error responses have charged: false. See Errors for retry guidance.