Find and verify a NIN record using a Nigerian phone number.
Verify an identity record using a Nigerian phone number.
POST /v1/verifications/nin/phone
| Property | Value |
|---|---|
| Scope | NIN_VERIFY |
| Live price | ₦120 |
| 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 |
|---|---|---|---|
phone | string | Yes | A valid Nigerian number such as 08012345678 or +2348012345678. |
{
"phone": "08012345678"
}cURL example
curl -X POST "https://api.idyntic.getapexly.com/v1/verifications/nin/phone" \
-H "Authorization: Bearer id_test_your_key" \
-H "Idempotency-Key: req_550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{"phone":"08012345678"}'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 (Phone) Successful",
"data": {
"reference": "550e8400-e29b-41d4-a716-446655440001",
"status": "SUCCESSFUL",
"type": "nin_phone",
"environment": "live",
"nin_data": {
"middlename": "ADAEZE",
"telephoneno": "08012345678",
"residence_town": "IKEJA",
"gender": "FEMALE",
"nin_suspension_status": false,
"birthdate": "05-12-1994",
"surname": "NWACHUKWU",
"residence_address": "24 SPECIMEN AVENUE, OFF DEMO ROAD",
"firstname": "CHIDINMA",
"residence_lga": "IKEJA",
"nin_suspension_message": "NOT SUSPENDED",
"photo": "/9j/4AAQSkZJRgABAQAAAQABAAD/2Q==",
"residence_state": "LAGOS",
"nin": "12345678901",
"pmiddlename": "",
"userid": "",
"self_origin_place": "",
"profession": "",
"trackingId": "",
"maritalstatus": "",
"self_origin_lga": "",
"nok_lga": "",
"vnin": "",
"nok_firstname": "",
"spoken_language": "",
"ospokenlang": "",
"nok_middlename": "",
"nok_town": "",
"heigth": "",
"educationallevel": "",
"nok_address2": "",
"nok_state": "",
"birthcountry": "",
"self_origin_state": "",
"nok_postalcode": "",
"religion": "",
"nok_address1": "",
"centralID": "",
"title": "",
"nok_surname": "",
"psurname": "",
"signature": "",
"birthlga": "",
"residencestatus": "",
"employmentstatus": "",
"birthstate": "",
"pfirstname": "",
"email": ""
}
},
"billing": {
"amount": 120,
"currency": "NGN",
"unit": "naira",
"charged": true,
"note": "Wallet charged 120.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_phone",
"environment": "live",
"nin_data": null
},
"billing": {
"amount": 120,
"currency": "NGN",
"unit": "naira",
"charged": true,
"note": "Wallet charged 120.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_phone",
"environment": "live",
"nin_data": null
},
"billing": {
"amount": 120,
"currency": "NGN",
"unit": "naira",
"charged": true,
"note": "Wallet charged 120.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 | Enter a valid Nigerian phone number (e.g. 08012345678 or +2348012345678) |
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 ₦120 |
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": "Enter a valid Nigerian phone number (e.g. 08012345678 or +2348012345678)",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
},
"billing": {
"amount": 120,
"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": 120,
"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": 120,
"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": 120,
"currency": "NGN",
"unit": "naira",
"charged": false,
"note": "No charges"
}
}All error responses have charged: false. See Errors for retry guidance.