Developer Documentation

Integrate iVerify.ng verification services into your application

Prerequisites

Before you begin integration, ensure you have completed the following:

  • Contract Signed: Reached out to the iVerify team and signed a partnership/contract agreement
  • Account Registration: Registered and verified your account on iverify.ng
  • Workspace Access: Created or have access to a workspace with appropriate permissions

Quick Start

Base URL:

https://api-test.iverify.ng

All API requests must be made over HTTPS. Include your Firebase ID token in the Authorization header for all requests.

Authentication Header:

Authorization: Bearer <idToken> Content-Type: application/json

Getting Your Workspace ID

Before making verification requests, you'll need to retrieve your workspaceId. This can be obtained from your user profile.

Endpoint:

GET /api/users/profile/me

Node.js Example:

// Get user profile to retrieve workspaceId
const response = await fetch('https://api-test.iverify.ng/users/profile/me', {
  headers: {
    'Authorization': `Bearer ${idToken}`
  }
});

const profile = await response.json();
// Extract workspaceId from the first workspace
const workspaceId = profile.workspaces[0]?.workspaceId;
console.log('Workspace ID:', workspaceId);

Sample Response:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "johndoe@example.com",
  "firebaseId": "WTRb500cMbPEzL2CRuEf39204l13",
  "id": "ee003a43-725c-4563-9939-4e4d385533a2",
  "appRoles": ["WORKSPACE"],
  "default_country": "NG",
  "emailVerified": true,
  "workspaces": [
    {
      "id": "cmj5tgkfb00021jmiji491uz2",
      "workspaceId": "cmj5tgkfa00001jmi9gkqvban",
      "userId": "ee003a43-725c-4563-9939-4e4d385323a2",
      "permissions": ["ADMIN", "OWNER", "REQUESTER", "VIEWER"],
      "mainRole": "OWNER",
      "workspace": {
        "id": "cmj5tgkfa00001jmi9gkqvban",
        "name": "John Doe Workspace",
        "active": true,
        "type": "PERSONAL"
      }
    }
  ]
}

The workspaceId can be found in the workspaces array at workspaces[0].workspaceId.

Service Request Endpoints

Identity Verification

POST /api/requests/new/id-verification

Verify government-issued identity documents (NIN, Driver's License, Passport, etc.)

Request Body Example:

{
  "workspaceId": "your-workspace-id",
  "country": "NG",
  "code": "NIN_VERIFICATION",
  "params": {
    "idNumber": "12345678901"
  }
}

Node.js Example:

const response = await fetch('https://api-test.iverify.ng/requests/new/id-verification', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${idToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    workspaceId: 'your-workspace-id',
    country: 'NG',
    code: 'NIN_VERIFICATION',
    params: {
      idNumber: '12345678901'
    }
  })
});

const result = await response.json();
console.log('Request ID:', result.request.id);
console.log('Payment URL:', result.payment?.paymentUrl);

Common Endpoints

MethodEndpointDescription
GET/api/requests/details/:requestIdGet request details and verification results
POST/api/requests/new/getCostCalculate the cost for a verification request
GET/api/servicesList all available services

Get Request Details Example:

// Get request details after verification is complete
const response = await fetch(`https://api-test.iverify.ng/requests/details/${requestId}`, {
  headers: {
    'Authorization': `Bearer ${idToken}`
  }
});

const details = await response.json();
console.log('Status:', details.status);
console.log('Report URL:', details.identity?.reportPdfUrl || details.employees?.[0]?.reportUrl);

Get Cost Example:

// Calculate cost before creating request
const response = await fetch('https://api-test.iverify.ng/requests/new/getCost', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${idToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: 'NIN_VERIFICATION',
    country: 'NG',
    quantity: 1
  })
});

const cost = await response.json();
console.log('Cost:', cost.amount, cost.currency);

Payment Integration

Offline Payment Mode

For third-party integrations with offline payment mode, payments are processed manually by the iVerify team. After creating a verification request:

  • The API will return a payment object with transaction reference
  • Contact the iVerify team with the transaction reference to process payment offline
  • Once payment is confirmed, verification will begin automatically
  • Monitor request status via polling or webhooks to know when verification completes

Request Lifecycle

Status Flow:

PENDING → ONGOING_VERIFICATION → COMPLETED → REJECTED → FAILED
StatusDescription
PENDINGRequest created, awaiting payment (for offline mode, contact iVerify team)
ONGOING_VERIFICATIONPayment successful, verification in progress
COMPLETEDVerification successfully completed
REJECTEDVerification failed (invalid data, document not found)
FAILEDSystem error or timeout

Support & Contact

Need Help?