NIN Verification by Phone

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

PropertyValue
ScopeNIN_VERIFY
Live price₦120
Test charge₦0
Idempotency-KeyRequired
⚠️

Check data.status

SUCCESSFUL, NOT_FOUND, and SUSPENDED are completed outcomes. They all return HTTP 200 and live requests are charged.

Headers

Authorization: Bearer id_test_your_key
Idempotency-Key: req_550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

Request body

FieldTypeRequiredDescription
phonestringYesA 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

HTTPCodeWhen it happens
400INVALID_REQUESTEnter a valid Nigerian phone number (e.g. 08012345678 or +2348012345678)
400INVALID_IDEMPOTENCY_KEYHeader is missing or does not match the required format
401UNAUTHORIZEDKey is invalid, expired, revoked, or lacks NIN_VERIFY
402INSUFFICIENT_BALANCELive wallet balance is below ₦120
409IDEMPOTENCY_KEY_REUSEDThe key was used with a different request body
409IDEMPOTENCY_IN_PROGRESSThe same live operation is still processing
429RATE_LIMIT_EXCEEDEDPer-key request limit was exceeded
500INTERNAL_ERRORAn unexpected error prevented completion
503SERVICE_UNAVAILABLEThe 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.