Reference

API Reference

The VerifyGuru API gives you programmatic access to Nigerian identity verification, bank account validation, and SMS messaging, all through a single, consistent REST interface.

Identity

BVN & NIN verification with smart caching

Banking

Real-time account & bank validation

Messaging

SMS & OTP delivery across Nigeria

Authentication

Every request must include your API key as a Bearer token in the Authorization header.

HTTP Header

Authorization: Bearer vg_your_api_key_here

Never expose your API key in client-side code or version control. Generate separate keys for development and production.

Base URL

All API requests must be made over HTTPS to the following base URL.

Base URL

https://verify-guru.com/api/v1

Health check: GET /api/v1/ping - returns {"status":"ok"} with no authentication required.

Error Handling

All errors return a consistent JSON body with status: false and a human-readable message.

Error Response

{
  "status": false,
  "message": "BVN must be exactly 11 digits"
}

HTTP Status Codes

Code	Meaning
200	Success
401	Missing or invalid API key
422	Validation error - check your request body
503	Service temporarily unavailable

GET /v1/banks

Fetch Banks

Returns a list of all supported banks with their codes. Use the bank_code when validating an account number.

curl -X GET https://verify-guru.com/api/v1/banks \
  -H "Authorization: Bearer vg_your_api_key_here" \
  -H "Accept: application/json"

$ch = curl_init('https://verify-guru.com/api/v1/banks');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer vg_your_api_key_here',
    'Accept: application/json',
]);
$response = json_decode(curl_exec($ch), true);

const res = await fetch('https://verify-guru.com/api/v1/banks', {
  headers: {
    'Authorization': 'Bearer vg_your_api_key_here',
    'Accept': 'application/json'
  }
});
const data = await res.json();

Response 200 OK

application/json

{
  "status": true,
  "message": "Banks fetched successfully",
  "data": {
    "banks": [
      {
        "bankName": "Guaranty Trust Bank",
        "bankCode": "058",
        "nibssBankCode": "000073"
      },
      {
        "bankName": "First Bank of Nigeria",
        "bankCode": "011",
        "nibssBankCode": "000016"
      }
    ]
  }
}

POST /v1/account/validate

Validate Bank Account

Resolve a 10-digit NUBAN account number to the registered account holder's name and details.

Request Body

Field	Type	Description
account_number required	string	10-digit NUBAN bank account number
bank_code required	string	3–6 digit bank code (from `/v1/banks`)

curl -X POST https://verify-guru.com/api/v1/account/validate \
  -H "Authorization: Bearer vg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"account_number":"0123456789","bank_code":"058"}'

$ch = curl_init('https://verify-guru.com/api/v1/account/validate');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer vg_your_api_key_here',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'account_number' => '0123456789',
        'bank_code'      => '058',
    ]),
]);
$response = json_decode(curl_exec($ch), true);

const res = await fetch('https://verify-guru.com/api/v1/account/validate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vg_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ account_number: '0123456789', bank_code: '058' })
});
const data = await res.json();

Response 200 OK

{
  "status": true,
  "message": "Account validated successfully",
  "data": {
    "number": "0123456789",
    "bank": "058",
    "name": "JOHN ADEWALE DOE",
    "kyc": "2"
  }
}

POST /v1/verify/bvn

Verify BVN

Verify a Bank Verification Number (BVN) and retrieve the associated identity data. Results are cached server-side - repeat lookups on the same BVN are served instantly at no additional cost.

Request Body

Field	Type	Description
bvn required	string	11-digit BVN number
firstname required	string	First name to match against BVN record.
lastname required	string	Last name to match against BVN record.
dob	string	Optional. Date of birth - format `DD-MM-YYYY`

curl -X POST https://verifyguru.xyz/api/v1/verify/bvn \
  -H "Authorization: Bearer vg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "bvn": "12345678901",
    "firstname": "John",
    "lastname": "Doe"
  }'

$ch = curl_init('https://verifyguru.xyz/api/v1/verify/bvn');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer vg_your_api_key_here',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'bvn'       => '12345678901',
        'firstname' => 'John',
        'lastname'  => 'Doe'
    ]),
]);
$response = json_decode(curl_exec($ch), true);

const res = await fetch('https://verifyguru.xyz/api/v1/verify/bvn', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vg_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ bvn: '12345678901', firstname: 'John', lastname: 'Doe' })
});
const data = await res.json();

Response 200 OK

{
  "status": true,
  "message": "BVN verified successfully",
  "data": {
    "status": "success",
    "data": {
      "bvn": "12345678901",
      "firstname": "John",
      "lastname": "Doe",
      "middlename": "Jane",
      "phone": "08066676673",
      "gender": "female",
      "birthdate": "04-04-1944",
      "maritalStatus": "Single",
      "lgaOfResidence": "Surulere",
      "residentialAddress": "1 Jameson Street",
      "stateOfOrigin": "Ogun State"
    }
  }
}

POST /v1/verify/nin

Verify NIN

Verify a National Identification Number (NIN) and retrieve the associated identity record. Results are cached server-side to reduce cost on repeated lookups.

Request Body

Field	Type	Description
nin required	string	11-digit National Identification Number
firstname required	string	First name to match against NIN record.
lastname required	string	Last name to match against NIN record.
dob	string	Optional. Date of birth - format `DD-MM-YYYY`

curl -X POST https://verifyguru.xyz/api/v1/verify/nin \
  -H "Authorization: Bearer vg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"nin": "12345678901", "firstname": "John", "lastname": "Doe"}'

$ch = curl_init('https://verifyguru.xyz/api/v1/verify/nin');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer vg_your_api_key_here',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['nin' => '12345678901', 'firstname' => 'John', 'lastname' => 'Doe']),
]);
$response = json_decode(curl_exec($ch), true);

const res = await fetch('https://verifyguru.xyz/api/v1/verify/nin', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vg_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ nin: '12345678901', firstname: 'John', lastname: 'Doe' })
});
const data = await res.json();

Response 200 OK

{
  "status": true,
  "message": "NIN verified successfully",
  "data": {
    "status": "success",
    "data": {
      "nin": "12345678901",
      "firstname": "John",
      "lastname": "Doe",
      "middlename": "James",
      "phone": "08033334444",
      "gender": "m",
      "birthdate": "1990-01-15",
      "photo": "base64_encoded_string",
      "address": "12 Marina Street, Lagos"
    }
  }
}

POST /v1/verify/face-match

Facial Recognition (Face Match)

Compare two facial images instantly to verify if they belong to the same person. This is ideal for matching a selfie against an ID card photo or a previously saved profile picture.

Request Body

Field	Type	Description
image1 required	string	The primary selfie image (base64 encoded string or data URI).
image2 required	string	The reference ID image to compare against (base64 encoded string or data URI).

curl -X POST https://verifyguru.xyz/api/v1/verify/face-match \
  -H "Authorization: Bearer vg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "image1": "base64_encoded_string_1",
    "image2": "base64_encoded_string_2"
  }'

$ch = curl_init('https://verifyguru.xyz/api/v1/verify/face-match');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer vg_your_api_key_here',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'image1' => 'base64_encoded_string_1',
        'image2' => 'base64_encoded_string_2'
    ]),
]);
$response = json_decode(curl_exec($ch), true);

const res = await fetch('https://verifyguru.xyz/api/v1/verify/face-match', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vg_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ 
    image1: 'base64_encoded_string_1', 
    image2: 'base64_encoded_string_2' 
  })
});
const data = await res.json();

Response 200 OK

{
  "status": true,
  "message": "Face match completed",
  "data": {
    "match": true,
    "similarity": 99.85
  }
}

POST /v1/sms/send

Send SMS

Send a plain text SMS message to any Nigerian mobile number.

Request Body

Field	Type	Description
to required	string	Nigerian phone number. Accepts `08012345678` or `+2348012345678`
message required	string	Message content. Maximum 160 characters.

curl -X POST https://verifyguru.xyz/api/v1/sms/send \
  -H "Authorization: Bearer vg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "08012345678",
    "message": "Your application has been approved.",
    "channel": "generic"
  }'

$ch = curl_init('https://verifyguru.xyz/api/v1/sms/send');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer vg_your_api_key_here',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to'      => '08012345678',
        'message' => 'Your application has been approved.',
        'channel' => 'generic',
    ]),
]);
$response = json_decode(curl_exec($ch), true);

const res = await fetch('https://verifyguru.xyz/api/v1/sms/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vg_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '08012345678',
    message: 'Your application has been approved.',
    channel: 'generic'
  })
});
const data = await res.json();

Response 200 OK

{
  "status": true,
  "message": "SMS sent successfully",
  "data": {
    "message_id": "9122821270554876574",
    "to": "2348012345678",
    "from": "VerifyGuru",
    "sms": "Your application has been approved.",
    "status": "Message Sent"
  }
}

POST /v1/sms/otp

Send OTP

Generate and deliver a numeric One-Time Password (OTP) via SMS. OTP generation, expiry, and retry limits on their side - you just pass the phone number and template.

Request Body

Field	Type	Description
to required	string	Recipient Nigerian phone number
message	string	Custom message template. Must contain `{pin}` placeholder. Default: "Your VerifyGuru OTP is {pin}. Do not share."
pin_length	integer	Length of OTP. Default: `6`
expiry	integer	OTP validity in minutes. Default: `10`

The {pin} placeholder in the message field is automatically replaced with the generated OTP before delivery. allows a maximum of 3 retry attempts per OTP.

curl -X POST https://verifyguru.xyz/api/v1/sms/otp \
  -H "Authorization: Bearer vg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "08012345678",
    "message": "Your verification code is {pin}. Expires in 10 minutes.",
    "pin_length": 6,
    "expiry": 10
  }'

$ch = curl_init('https://verifyguru.xyz/api/v1/sms/otp');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer vg_your_api_key_here',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to'         => '08012345678',
        'message'    => 'Your verification code is {pin}. Expires in 10 minutes.',
        'pin_length' => 6,
        'expiry'     => 10,
    ]),
]);
$response = json_decode(curl_exec($ch), true);

const res = await fetch('https://verifyguru.xyz/api/v1/sms/otp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vg_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '08012345678',
    message: 'Your verification code is {pin}. Expires in 10 minutes.',
    pin_length: 6,
    expiry: 10
  })
});
const data = await res.json();

Response 200 OK

{
  "status": true,
  "message": "OTP sent successfully",
  "data": {
    "pinId": "29gdoa17-zaslk01-0029192a-12391291",
    "to": "2348012345678",
    "smsStatus": "Message Sent"
  }
}

POST /v1/sms/otp/verify

Verify OTP

Verify an OTP pin using the pin_id returned from the Send OTP endpoint. This is a free endpoint.

Request Body

Field	Type	Description
pin_id required	string	The PIN ID returned when sending the OTP.
pin required	string	The numeric PIN the user entered.

curl -X POST https://verifyguru.xyz/api/v1/sms/otp/verify \
  -H "Authorization: Bearer vg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "pin_id": "c8d44e5d-xxxx-xxxx",
    "pin": "123456"
  }'

$ch = curl_init('https://verifyguru.xyz/api/v1/sms/otp/verify');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer vg_your_api_key_here',
        'Content-Type: application/json',
        'Accept: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'pin_id' => 'c8d44e5d-xxxx-xxxx',
        'pin'    => '123456'
    ])
]);
$response = json_decode(curl_exec($ch), true);

const res = await fetch('https://verifyguru.xyz/api/v1/sms/otp/verify', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vg_your_api_key_here',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    pin_id: "c8d44e5d-xxxx-xxxx",
    pin: "123456"
  })
});
const data = await res.json();

Response 200 OK

application/json

{
  "status": true,
  "message": "OTP verified successfully",
  "data": {
    "pinId": "c8d44e5d-xxxx-xxxx",
    "verified": "true",
    "msisdn": "2348012345678"
  }
}

Response Format

All responses follow the same envelope structure.

Success Response Envelope

{
  "status": true,
  "message": "Human-readable success message",
  "data": { }
}