API Documentation
Get Started

Ready to integrate?

Create Account

API Documentation

Welcome to the TrustyDigits API documentation. Our comprehensive REST API enables you to verify Nigerian National Identity Numbers (NIN) and Bank Verification Numbers (BVN) programmatically with industry-leading accuracy.

Fast & Reliable

Average response time under 2 seconds with 99.9% uptime.

Secure

Bank-grade security with SSL encryption and secure authentication.

Developer Friendly

RESTful API with comprehensive documentation and SDKs.

Base URL
https://trustydigits.ng/api/v1

Note: All requests require wallet funding. Each verification costs ₦50.00

Authentication

All API requests require authentication using API keys. Include your API key in the request headers.

Authentication Header
Authorization: Bearer YOUR_API_KEY
Example Request
curl -X POST \
  https://trustydigits.ng/api/v1/verify \
  -H 'Authorization: Bearer kv_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{"nin": "12345678901"}'

Rate Limits

API requests are subject to rate limiting to ensure fair usage and system stability.

Plan Requests per Month Burst Limit Response Headers
Free 1,000 10/minute X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
Pro 10,000 50/minute Same as above
Enterprise Unlimited Custom Same as above

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of requests.

Code Status Description
200 OK Request successful
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing API key
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error occurred
Error Response Format
{
  "success": false,
  "error": {
    "code": "INVALID_NIN",
    "message": "The provided NIN is invalid or not found",
    "details": "NIN must be exactly 11 digits"
  }
}

Photo Handling

NIN verification responses include base64-encoded photos that can be displayed or processed directly.

Photo Format
  • Format: JPEG image encoded as base64 string
  • Data URI: Includes MIME type prefix (data:image/jpeg;base64,)
  • Size: Typically 150x200 pixels
  • File Size: Usually 15-50KB when decoded
Display Photo in HTML
<img src="data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..." 
     alt="NIN Photo" 
     style="max-width: 150px; border-radius: 8px;" />
Extract Base64 Data
// JavaScript example
const photoData = response.data.photo;
const base64Data = photoData.split(',')[1]; // Remove data URI prefix
const imageBlob = atob(base64Data); // Decode base64
Save Photo (PHP Example)
$photoData = $response['data']['photo'];
$base64Data = explode(',', $photoData)[1];
$imageData = base64_decode($base64Data);
file_put_contents('nin_photo.jpg', $imageData);
Privacy Notice: Photos contain sensitive biometric data. Ensure compliance with data protection regulations when storing or processing photos.

NIN Verification

Verify Nigerian National Identity Numbers and retrieve associated personal information.

Verify NIN
POST
/api/v1/verify
Request Parameters
Parameter Type Required Description
nin string Yes 11-digit National Identity Number
Example Request
curl -X POST \
  https://trustydigits.ng/api/v1/verify \
  -H 'Authorization: Bearer kv_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "nin": "12345678901"
  }'
Success Response (200 OK)
{
  "success": true,
  "data": {
    "nin": "12345678901",
    "firstname": "John",
    "lastname": "Doe",
    "middlename": "Michael",
    "phone": "08012345678",
    "birthdate": "1990-01-01",
    "gender": "Male",
    "photo": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBA...",
    "verification_id": "vrf_1234567890"
  },
  "meta": {
    "request_id": "req_abcd1234",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
Photo Field: The photo field contains a base64-encoded JPEG image of the NIN holder. You can display this directly in HTML using: <img src="data:image/jpeg;base64,..." />
Error Response (400 Bad Request)
{
  "success": false,
  "error": {
    "code": "INVALID_NIN",
    "message": "The provided NIN is invalid or not found"
  }
}

BVN Verification

Verify Bank Verification Numbers and retrieve associated banking information.

Verify BVN
POST
/api/v1/verify
Request Parameters
Parameter Type Required Description
bvn string Yes 11-digit Bank Verification Number
Example Request
curl -X POST \
  https://trustydigits.ng/api/v1/verify \
  -H 'Authorization: Bearer kv_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "bvn": "22222222222"
  }'
Success Response (200 OK)
{
  "success": true,
  "data": {
    "bvn": "22222222222",
    "first_name": "Jane",
    "last_name": "Smith",
    "middle_name": "Anne",
    "phone_number1": "08087654321",
    "date_of_birth": "1985-05-15",
    "gender": "Female",
    "verification_id": "vrf_0987654321"
  },
  "meta": {
    "request_id": "req_efgh5678",
    "timestamp": "2024-01-15T10:35:00Z"
  }
}

Wallet Balance

Check your current wallet balance and recent transactions.

Get Wallet Balance
GET
/api/v1/balance
Example Request
curl -X GET \
  https://trustydigits.ng/api/v1/balance \
  -H 'Authorization: Bearer kv_your_api_key_here'
Success Response (200 OK)
{
  "success": true,
  "message": "Balance retrieved successfully",
  "data": {
    "balance": 1500.00,
    "currency": "NGN",
    "account_number": "9012345678",
    "recent_transactions": [
      {
        "id": 123,
        "type": "debit",
        "amount": 50.00,
        "description": "API NIN Verification - 12345678901",
        "balance_after": 1500.00,
        "date": "2024-01-15T10:30:00Z"
      }
    ]
  }
}

Verification History

Retrieve your verification history with pagination and filtering options.

Get Verification History
GET
/api/v1/history
Query Parameters
Parameter Type Required Description
page integer No Page number (default: 1)
limit integer No Records per page (default: 20, max: 100)
type string No Filter by type: NIN or BVN
status string No Filter by status: pending, verified, failed
Example Request
curl -X GET \
  'https://trustydigits.ng/api/v1/history?page=1&limit=10&type=NIN' \
  -H 'Authorization: Bearer kv_your_api_key_here'
Success Response (200 OK)
{
  "success": true,
  "message": "Verification history retrieved successfully",
  "data": {
    "verifications": [
      {
        "id": 456,
        "type": "NIN",
        "verification_data": "12345678901",
        "status": "verified",
        "cost": 50.00,
        "verified_data": {
          "nin": "12345678901",
          "firstname": "John",
          "lastname": "Doe",
          "middlename": "Michael",
          "phone": "08012345678",
          "birthdate": "1990-01-01",
          "gender": "Male"
        },
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_records": 87,
      "limit": 10,
      "has_next": true,
      "has_previous": false
    }
  }
}

API Status

Check the current status and health of the API service.

Get API Status
GET
/api/v1/status

Note: This endpoint does not require authentication.

Example Request
curl -X GET https://trustydigits.ng/api/v1/status
Success Response (200 OK)
{
  "success": true,
  "message": "API is operational",
  "data": {
    "status": "operational",
    "version": "v1",
    "timestamp": "2024-01-15T10:30:00Z",
    "uptime": "Available",
    "endpoints": {
      "POST /verify": "available",
      "GET /balance": "available",
      "GET /history": "available",
      "GET /status": "available"
    }
  }
}

SDKs & Libraries

Official SDKs and community libraries to integrate with your favorite programming language.

JavaScript/Node.js
npm install kyc-verify-sdk

Official JavaScript SDK for browser and Node.js

Coming Soon
Python
pip install kyc-verify

Official Python SDK with asyncio support

Coming Soon
PHP
composer require kyc-verify/php-sdk

Official PHP SDK with Laravel support

Coming Soon
HTTP/cURL

Use any HTTP client or cURL commands

Available

Support

Need help integrating or have questions about the API? We're here to help.

API Support

Get help with integration and technical issues

Contact Support
Knowledge Base

Browse our collection of guides and tutorials

Browse Articles
Still have questions?

Our developer support team is available 24/7 to help you integrate successfully.

Get Help