API Documentation

NIN, BVN, and Phone verification endpoints. Get started with code examples in your language.

Authentication

Base URL

https://api.provn.ng

Required Headers

API-KeyYour organization API key. Test keys are prefixed with test_

Access-KeyYour organization UUID

Content-Typeapplication/json

Requests fail if the API-Key organization and Access-Key organization do not match.

Success Response

JSON
{
  "status": "success",
  "code": 200,
  "message": "Verification successful",
  "data": { ... }
}

Error Response

JSON
{
  "detail": "Human-readable error message"
}

Test vs Live Mode

Behavior	Test Key	Live Key
Wallet charge	No	Yes
Response data	Dummy payload	Live payload
Failure refund	N/A	Automatic

POST/verification/nin

NIN Verification

Verifies a National Identification Number and returns standardized identity fields.

Required fieldnin

ValidationExactly 11 digits.

Request

curl -X POST "https://api.provn.ng/verification/nin" \
  -H "Content-Type: application/json" \
  -H "API-Key: YOUR_API_KEY" \
  -H "Access-Key: YOUR_ORG_UUID" \
  -d '{"nin":"12345678901"}'

Response

JSON
{
  "status": "success",
  "code": 200,
  "message": "Verification successful",
  "data": {
    "nin": "12345678901",
    "first_name": "John",
    "last_name": "Doe",
    "middle_name": "Dummy",
    "phone_number": "08012345678",
    "date_of_birth": "1990-01-01",
    "state_of_origin": "Lagos",
    "photo": "base64_encoded_image_data"
  }
}

POST/verification/bvn

BVN Verification

Verifies a Bank Verification Number and returns standardized banking identity fields.

Required fieldbvn

ValidationExactly 11 digits.

Request

curl -X POST "https://api.provn.ng/verification/bvn" \
  -H "Content-Type: application/json" \
  -H "API-Key: YOUR_API_KEY" \
  -H "Access-Key: YOUR_ORG_UUID" \
  -d '{"bvn":"12345678901"}'

Response

JSON
{
  "status": "success",
  "code": 200,
  "message": "Verification successful",
  "data": {
    "bvn": "12345678901",
    "first_name": "John",
    "last_name": "Doe",
    "middle_name": "Dummy",
    "phone_number": "08012345678",
    "date_of_birth": "1990-01-01",
    "residential_address": "123 Test Street, Lagos",
    "state_of_origin": "Lagos",
    "photo": "base64_encoded_image_data"
  }
}

POST/verification/phone

Phone Verification

Validates Nigerian phone numbers and returns network and country metadata.

Required fieldphone

Validation11 digits, must start with 0.

Request

curl -X POST "https://api.provn.ng/verification/phone" \
  -H "Content-Type: application/json" \
  -H "API-Key: YOUR_API_KEY" \
  -H "Access-Key: YOUR_ORG_UUID" \
  -d '{"phone":"08012345678"}'

Response

JSON
{
  "status": "success",
  "code": 200,
  "message": "Verification successful",
  "data": {
    "phone": "08012345678",
    "is_valid": true,
    "network": "MTN",
    "country": "Nigeria"
  }
}

Error Reference

Common Errors (All Endpoints)

HTTP	Error	Fix
401	Authentication required. Provide API-Key header.	Add API-Key header with your organization API key.
401	Access key required. Provide Access-Key header.	Add Access-Key header using your organization UUID.
401	Invalid API key	Regenerate key in dashboard and retry.
403	Access key does not match the API key's organization.	Use the Access-Key for the same organization that owns the API key.
403	Organization owner has toggled to test credentials.	Switch to test key or toggle organization to live mode.
403	Verification is disabled for this organization.	Enable the service in your organization config.
404	Wallet not found. Please create a wallet first.	Create a wallet from the dashboard before calling verification.
400	Insufficient wallet balance.	Fund your wallet or adjust pricing/discount settings.
500	Verification failed: <reason>	Retry with exponential backoff, then contact support.

Validation Errors

Service	HTTP	Error
NIN	400	Invalid NIN. NIN must be exactly 11 digits.
BVN	400	Invalid BVN. BVN must be exactly 11 digits.
Phone	400	Phone number is required.
Phone	400	Invalid phone number format. Expected 11 digits starting with 0.