NIN Verification

Verify an identity using an 11-digit NIN.

Verify an identity record using an 11-digit NIN.

POST /v1/verifications/nin

PropertyValue
ScopeNIN_VERIFY
Live price₦100
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
ninstringYesExactly 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

HTTPCodeWhen it happens
400INVALID_REQUESTNIN must be 11 digits
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 ₦100
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": "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.