Veriglobe API Documentation

Getting Started

This documentation will help you integrate Veriglobe's identity verification services into your application. If you need any assistance, please contact our support team.

The Veriglobe API provides a comprehensive suite of identity verification services, allowing developers to integrate KYC (Know Your Customer) functionality into their applications.

Our API enables you to verify various forms of identification including Bank Verification Numbers (BVN), National Identification Numbers (NIN), identity documents, and address information.

Simplified URL Format

All API endpoints now support a cleaner URL format without the "index.php" prefix. For example, you can use /generate_kyc_link instead of /index.php/generate_kyc_link. Both formats will continue to work for backward compatibility.

Generate KYC Link

Create a verification session and get a link for your customers to complete verification.

Retrieve User Data

Access comprehensive verification data for your customers after they complete the process.

List Verifications

View all verification sessions for your projects and track their status.

Base URL

https://api.veriglobe.net/

API Flow

Standard Verification Flow

Generate a KYC link for your customer using the generate_kyc_link endpoint
Store the verification_id returned in the response
Redirect your customer to the provided KYC link to complete verification
Receive verification results via callback (if configured) or retrieve them via the user_data endpoint using the verification_id

Direct API Verification Flow

Collect required verification data from your customer (BVN/NIN/CAC details)
Submit the data directly to the appropriate verification endpoint (verify_bvn, verify_nin, or verify_cac)
Process the verification result returned in the response
Store the verification_id for future reference

Authentication

Most API requests require authentication using both API keys. Include your API keys in the request headers:

Public-Key: YOUR_PUBLIC_KEY
Private-Key: YOUR_PRIVATE_KEY

Simplified Authentication

The Generate KYC Link endpoint now only requires the Public Key for authentication:

Public-Key: YOUR_PUBLIC_KEY

You can obtain your API keys from the Veriglobe dashboard under API & Settings.

Security Notice

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.

Security Best Practices

Never expose your private key in client-side code or public repositories
Always use HTTPS for API calls to ensure data is encrypted in transit
Rotate your API keys periodically to minimize security risks
Implement proper error handling for authentication failures

API Reference

Veriglobe provides a comprehensive set of API endpoints for identity verification. Below is a complete list of available endpoints. Click on any endpoint to view detailed documentation.

Verification Management

POST

generate_kyc_link

Create a verification session and get a link for your customers to complete verification

POST

user_data

Retrieve verification data for a completed verification

POST

get_user_data

Retrieve comprehensive data about a verified user

POST

list_verifications

Retrieve a list of verifications for a specific project

Direct Verification APIs

POST

verify_bvn

Directly verify a Bank Verification Number (BVN) against provided personal details

POST

verify_nin

Directly verify a National Identification Number (NIN) against provided personal details

POST

verify_cac

Directly verify a Corporate Affairs Commission (CAC) Certificate of Incorporation

Generate KYC Link

Endpoint Overview

This endpoint creates a verification session and returns a link that can be used to complete the verification process. The response includes both the verification_id and the KYC link.

Simplified Usage: This endpoint now only requires your Public Key for authentication. All other parameters are optional, making it much easier to generate KYC links with minimal configuration.

Simplified URL Format: All API endpoints now support a cleaner URL format without the "index.php" prefix. For example, you can use /generate_kyc_link instead of /index.php/generate_kyc_link. Both formats will continue to work.

POST generate_kyc_link

Headers

Content-Type
application/json
Public-Key
Your public API key

Request Body

project_id Optional
Your project ID (if not provided, default project will be used)
customer_name Optional
The name of the customer to verify (if not provided, a default name will be generated)
callback_url Optional
URL to receive verification results (if provided, must be a valid URL)

{
  "project_id": "YOUR_PROJECT_ID",  // Optional - default project will be used if not provided
  "customer_name": "John Doe",      // Optional - default name will be generated if not provided
  "callback_url": "https://your-website.com/callback"  // Optional
}

Simplified Usage

With the updated API, you can now generate a KYC link with just the Public Key in the header:

{
  // Empty request body is valid - all defaults will be used
}

{
  "verification_id": "123",
  "kyc_link": "https://verify.veriglobe.net?verification_id=123&project_id=456&customer_name=John%20Doe"
}

Tip

Store the verification_id in your database. You'll need it later to retrieve the verification results.

Retrieve User Data

Retrieves the verification data for a completed verification.

POST user_data

Headers

Content-Type
application/json
Public-Key
Your public API key
Private-Key
Your private API key

Request Body

verification_id Required
The ID of the verification to retrieve
project_id Required
Your project ID

Example Request

{
  "verification_id": "VERIFICATION_ID",
  "project_id": "YOUR_PROJECT_ID"
}

Response

{
  "user_data": {
    "verification_id": "123",
    "customer_name": "John Doe",
    "bvn_status": "Verified",
    "nin_status": "Verified",
    "identity_status": "Verified",
    "address_status": "Verified",
    "bvn": "12345678901",
    "nin": "12345678901",
    "user_picture_url": "https://example.com/uploads/user_123.jpg",
    "id_picture_url": "https://example.com/uploads/id_123.jpg",
    "address": "123 Main Street, Lagos, Nigeria",
    "verification_time_seconds": 120,
    "verdict": "Completed"
  }
}

Get User Data

Retrieves comprehensive data about a verified user. This endpoint is particularly useful for mobile applications that need to display detailed information about users who have completed the verification process.

POST get_user_data

Headers

Content-Type
application/json
Public-Key
Your public API key
Private-Key
Your private API key

Request Body

verification_id Required
The ID of the verification to retrieve data for

Example Request

{
  "verification_id": "VERIFICATION_ID"
}

Response

{
  "user_data": {
    "verification_id": "123",
    "project_id": "456",
    "customer_name": "John Doe",
    "nin_status": "Verified",
    "bvn_status": "Verified",
    "address_status": "Verified",
    "identity_status": "Verified",
    "verdict": "Completed",
    "verification_time_seconds": 120,
    "verification_date": "2023-01-01 12:00:00",
    "nin": "12345678901",
    "bvn": "12345678901",
    "address": "123 Main Street, Lagos, Nigeria",
    "user_picture_url": "https://example.com/uploads/user_123.jpg",
    "id_picture_url": "https://example.com/uploads/id_123.jpg"
  }
}

List Verifications

Retrieves a list of verifications for a specific project. This endpoint is particularly useful for mobile applications to find the verification_id for a specific customer.

POST list_verifications

Headers

Content-Type
application/json
Public-Key
Your public API key
Private-Key
Your private API key

Request Body

project_id Required
The ID of the project to list verifications for
limit Optional
Maximum number of verifications to return (default: 100)
offset Optional
Number of verifications to skip (default: 0)

Example Request

{
  "project_id": "YOUR_PROJECT_ID",
  "limit": 100,
  "offset": 0
}

Response

{
  "verifications": [
    {
      "verification_id": "123",
      "customer_name": "John Doe",
      "nin_status": "Verified",
      "bvn_status": "Verified",
      "address_status": "Verified",
      "identity_status": "Verified",
      "verdict": "Completed",
      "created_at": "2023-01-01 12:00:00"
    },
    {
      "verification_id": "124",
      "customer_name": "Jane Smith",
      "nin_status": "Verified",
      "bvn_status": "Verified",
      "address_status": "Pending",
      "identity_status": "Verified",
      "verdict": "Pending Manual Review",
      "created_at": "2023-01-02 14:30:00"
    }
  ]
}

Verify BVN (Direct API)

Directly verifies a Bank Verification Number (BVN) against the provided personal details. This endpoint charges 0.5 credits from your credit balance per verification.

POST verify_bvn

Headers

Content-Type
application/json

Required
Public-Key
YOUR_PUBLIC_KEY

Required
Private-Key
YOUR_PRIVATE_KEY

Required

Request Body

bvn
The 11-digit Bank Verification Number

Required
first_name
The first name of the BVN holder

Required
last_name
The last name of the BVN holder

Required
date_of_birth
The date of birth in YYYY-MM-DD format

Required
project_id
Your project ID

Required

Request Example

{
  "bvn": "12345678901",
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1990-01-01",
  "project_id": "YOUR_PROJECT_ID"
}

Response Example

{
  "status": true,
  "message": "BVN verified successfully",
  "verification_id": "BVN_5f8a9b3c2d1e",
  "verification_timestamp": "2025-12-19 17:45:18",
  "verification_type": "BVN",
  "verification_method": "API",
  "identity_data": {
    "first_name": "John",
    "last_name": "Doe",
    "middle_name": "Smith",
    "full_name": "John Smith Doe",
    "gender": "Male",
    "date_of_birth": "1990-01-01",
    "photo": true,
    "bvn": "12345678901",
    "phone_number": "08012345678",
    "email": "john.doe@example.com",
    "nationality": "Nigerian",
    "state_of_origin": "Lagos",
    "lga_of_origin": "Ikeja",
    "address": "123 Example Street, Ikeja, Lagos",
    "marital_status": "Single",
    "match_result": {
      "first_name": true,
      "last_name": true,
      "date_of_birth": true
    }
  },
  "meta": {
    "api_version": "1.1",
    "provider": "Veriglobe",
    "source": "NIBSS via Veri"
  }
}

Note

This endpoint charges 0.5 credits from your credit balance for each verification request. Ensure you have sufficient balance before making the request.

Verify NIN (Direct API)

Directly verifies a National Identification Number (NIN) against the provided personal details. This endpoint charges 0.5 credits from your credit balance per verification.

POST verify_nin

Headers

Content-Type
application/json

Required
Public-Key
YOUR_PUBLIC_KEY

Required
Private-Key
YOUR_PRIVATE_KEY

Required

Request Body

nin
The 11-digit National Identification Number

Required
first_name
The first name of the NIN holder

Required
last_name
The last name of the NIN holder

Required
date_of_birth
The date of birth in YYYY-MM-DD format

Required
project_id
Your project ID

Required

Request Example

{
  "nin": "12345678901",
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1990-01-01",
  "project_id": "YOUR_PROJECT_ID"
}

Response Example

{
  "status": true,
  "message": "NIN verified successfully",
  "verification_id": "NIN_5f8a9b3c2d1e",
  "verification_timestamp": "2025-12-19 17:45:18",
  "verification_type": "NIN",
  "verification_method": "API",
  "identity_data": {
    "first_name": "John",
    "last_name": "Doe",
    "middle_name": "Smith",
    "full_name": "John Smith Doe",
    "gender": "Male",
    "date_of_birth": "1990-01-01",
    "photo": true,
    "nin": "12345678901",
    "phone_number": "08012345678",
    "email": "john.doe@example.com",
    "nationality": "Nigerian",
    "state_of_origin": "Lagos",
    "lga_of_origin": "Ikeja",
    "address": "123 Example Street, Ikeja, Lagos",
    "marital_status": "Single",
    "match_result": {
      "first_name": true,
      "last_name": true,
      "date_of_birth": true
    }
  },
  "meta": {
    "api_version": "1.1",
    "provider": "Veriglobe",
    "source": "NIMC via Veri"
  }
}

Note

This endpoint charges 0.5 credits from your credit balance for each verification request. Ensure you have sufficient balance before making the request.

Verify CAC (Direct API)

Directly verifies a Corporate Affairs Commission (CAC) Certificate of Incorporation against the provided business details. This endpoint charges 0.5 credits from your credit balance per verification.

POST verify_cac

Headers

Content-Type
application/json
Public-Key
YOUR_PUBLIC_KEY
Private-Key
YOUR_PRIVATE_KEY

Request Body

cac_id Required
The CAC registration number (e.g., RC00000011)
registration_name Optional
The registered name of the business
verification_consent Required
Boolean indicating that subject has given consent to perform this verification (must be true)
project_id Required
Your project ID

Example Request

{
  "cac_id": "RC00000011",
  "registration_name": "Example Business Ltd",
  "verification_consent": true,
  "project_id": "YOUR_PROJECT_ID"
}

Response Example

{
  "status": true,
  "message": "CAC verified successfully",
  "verification_id": "CAC_123456789",
  "verification_timestamp": "2025-12-19 17:45:18",
  "verification_type": "CAC",
  "verification_method": "API",
  "business_data": {
    "id": "RC00000011",
    "id_type": "ng_cac",
    "name": "Example Business Ltd",
    "email": "contact@example.com",
    "phone_number": "+234 000 000 0000",
    "registration_number": "RC00000011",
    "registration_date": "2017-06-09T00:00:00.000+00:00",
    "type_of_entity": "PRIVATE COMPANY LIMITED BY SHARES",
    "address": "123 Example Street",
    "state": "LAGOS",
    "company_status": "ACTIVE"
  },
  "meta": {
    "api_version": "1.1",
    "provider": "Veriglobe",
    "source": "CAC via Veri"
  }
}

Note

This endpoint requires sufficient credits in your account. Each verification costs 0.5 credits.

Error Handling

All API endpoints return a standardized error response format that includes an error code, message, and optional details. This consistent format makes it easier to handle errors in your application.

Standard Error Response Format

{
  "status": false,
  "error": {
    "code": 400,
    "message": "Error message describing the issue",
    "details": {
      "field1": "Additional information about the error",
      "field2": "More context about what went wrong"
    }
  }
}

Standard Error Codes

Error Code	HTTP Status	Description
400	400 Bad Request	Missing or invalid parameters
401	401 Unauthorized	Authentication failed or invalid API credentials
402	402 Payment Required	Insufficient credits for the requested operation
403	403 Forbidden	Access denied or invalid project ID
404	404 Not Found	Requested resource not found
422	422 Unprocessable Entity	Data validation failed
500	500 Internal Server Error	General server error
503	503 Service Unavailable	External service unavailable
505	500 Internal Server Error	Database error

Error Response Examples

Missing Required Parameter

{
  "status": false,
  "error": {
    "code": 400,
    "message": "BVN is required"
  }
}

Insufficient Credits

{
  "status": false,
  "error": {
    "code": 402,
    "message": "Insufficient credits for BVN verification",
    "details": {
      "required": 0.5,
      "available": 0.2
    }
  }
}

Service Unavailable

{
  "status": false,
  "error": {
    "code": 503,
    "message": "Connection to verification service failed",
    "details": {
      "detail": "Service timeout"
    }
  }
}

Best Practice

Always check for the presence of an error object in the response and handle it appropriately in your application. The error code can be used to determine the type of error and take appropriate action.