Services

Copy page

Identity Verification

Extract and verify data from identity documents including Omang, Passport, Driver's License, and Residence Permits.

Overview

The Identity Verification service provides comprehensive identity document processing with AI-powered data extraction and optional government database validation.

Base Path: /v1/identity

Available Endpoints

ID Scan - Extract Data from Documents

Extract structured data from identity documents with automatic front/back merging.

Endpoint: POST /v1/identity/scan

What it does:

• Extracts name, ID number, date of birth, photo, and other fields
• Supports Omang, Passport, Driver's License, Residence Permit
• Automatically merges front and back images
• Returns extracted data with confidence scores

Supported Documents:

• 🆔 Omang (Botswana National ID)
• 🛂 Passport
• 🚗 Driver's License
• 📋 Residence Permit

Request:

Code
 
curl -X POST https://api.botskyc.com/v1/identity/scan \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]"

Response:

Code
 
{
  "status": "success",
  "totalDocuments": 2,
  "processingTime": "2.8s",
  "extractedData": {
    "name": "John Doe",
    "idNumber": "123456789",
    "dateOfBirth": "1990-01-15",
    "nationality": "Botswana",
    "gender": "Male",
    "expiryDate": "2030-01-15",
    "placeOfBirth": "Gaborone",
    "photo": "base64-encoded-photo..."
  },
  "confidence": 98.5,
  "documentType": "OMANG",
  "verificationType": "IDENTITY"
}

Use Cases:

• Customer onboarding for banks
• SIM registration for telecoms
• Account verification
• Age verification

Pricing: BWP 5-8 per scan

---

ID Verify - Validate Against Government Database

Validate extracted identity data against the Omang Office database.

Endpoint: POST /v1/identity/verify

Status: 🚧 Coming Q1 2026

What it will do:

• Verify ID number exists in government database
• Confirm personal details match official records
• Check if ID is expired or revoked
• Detect fraudulent or tampered documents

---

Liveness Check - Verify Real Person

Create a face liveness verification session to ensure a real person is present.

Endpoint: POST /v1/identity/liveness

What it does:

• Creates a liveness verification session
• Returns session ID for frontend integration
• Anti-spoofing: detects photos, videos, masks

Request:

Code
 
curl -X POST https://api.botskyc.com/v1/identity/liveness \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"auditImagesLimit": 4}}'

Response:

Code
 
{
  "sessionId": "abc123-def456-ghi789",
  "status": "CREATED",
  "createdAt": "2025-11-24T12:30:00Z",
  "expiryDate": "2025-11-24T12:40:00Z"
}

Get Results:

Code
 
curl https://api.botskyc.com/v1/identity/liveness/abc123-def456-ghi789/results \
  -H "Authorization: Bearer YOUR_API_KEY"

See Liveness Detection for complete guide.

---

Face Match - Compare Selfie to ID Photo

Compare a live selfie with the photo from an identity document.

Endpoint: POST /v1/identity/face-match

What it does:

• Compares two face images
• Returns similarity score (0-100)
• Determines if faces match (threshold: 90%)

Request:

Code
 
curl -X POST https://api.botskyc.com/v1/identity/face-match \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]"

Response:

Code
 
{
  "similarity": 95.3,
  "isMatch": true,
  "confidence": 95.3,
  "threshold": 90.0
}

---

Complete KYC Workflow

Combine all identity verification features in one flow:

1. ID Scan - Extract data from Omang/Passport
2. Liveness Check - Verify real person present
3. Face Match - Compare selfie to ID photo
4. ID Verify (Coming Soon) - Validate against database

Example Workflow:

Code
 
// Step 1: Extract data from ID document
const scanResponse = await fetch('https://api.botskyc.com/v1/identity/scan', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}` },
  body: formDataWithIdImages
});

const { extractedData } = await scanResponse.json();

// Step 2: Create liveness session
const livenessResponse = await fetch('https://api.botskyc.com/v1/identity/liveness', {
  method: 'POST',
  headers: { 
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ settings: { auditImagesLimit: 4 } })
});

const { sessionId } = await livenessResponse.json();

// Step 3: User completes liveness check in frontend
// ... (using AWS Amplify UI FaceLivenessDetector component)

// Step 4: Get liveness results
const resultsResponse = await fetch(
  `https://api.botskyc.com/v1/identity/liveness/${sessionId}/results`,
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);

const { isLive, referenceImage } = await resultsResponse.json();

// Step 5: Compare face from liveness to ID photo
const matchResponse = await fetch('https://api.botskyc.com/v1/identity/face-match', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}` },
  body: createMatchFormData(extractedData.photo, referenceImage)
});

const { isMatch } = await matchResponse.json();

// All checks passed!
if (isLive && isMatch) {
  console.log('KYC verification complete ✓');
}

Best Practices

Image Quality

For best results:

• Minimum resolution: 1200x800 pixels
• Clear, well-lit images without glare
• All text legible and in focus
• No shadows or obstructions
• Flat surface - avoid curved or folded documents

File Formats

• Supported: JPG, JPEG, PNG, PDF
• Max file size: 10MB per file
• Max files per request: 10 files

Submission Strategies

Front & Back Separately:

Code
 
-F "[email protected]" \
-F "[email protected]"

Single PDF:

Code
 
-F "[email protected]"

The system automatically detects and merges front/back images.

Error Handling

Handle low confidence scores gracefully:

Code
 
const response = await scanIdentity(files);

if (response.confidence < 80) {
  // Ask user to retake photo
  alert('Image quality too low. Please retake photo in better lighting.');
} else if (response.confidence < 90) {
  // Request manual review
  await flagForManualReview(response);
} else {
  // High confidence - proceed
  await processKyc(response.extractedData);
}

Integration Examples

JavaScript

Code
 
async function scanIdentity(frontFile, backFile) {
  const formData = new FormData();
  formData.append('documents', frontFile);
  formData.append('documents', backFile);
  
  const response = await fetch('https://api.botskyc.com/v1/identity/scan', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.BOTSKYC_API_KEY}`
    },
    body: formData
  });
  
  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }
  
  return response.json();
}

// Usage
const result = await scanIdentity(omangFront, omangBack);
console.log('Extracted name:', result.extractedData.name);

Python

Code
 
import requests
import os

def scan_identity(front_path, back_path):
    api_key = os.getenv('BOTSKYC_API_KEY')
    
    files = {
        'documents': [
            ('documents', open(front_path, 'rb')),
            ('documents', open(back_path, 'rb'))
        ]
    }
    
    response = requests.post(
        'https://api.botskyc.com/v1/identity/scan',
        headers={'Authorization': f'Bearer {api_key}'},
        files=files
    )
    
    response.raise_for_status()
    return response.json()

# Usage
result = scan_identity('omang-front.jpg', 'omang-back.jpg')
print(f"Extracted name: {result['extractedData']['name']}")

Pricing

Product	Price per Request	Use Case
ID Scan	BWP 5-8	Data extraction only
ID Verify	TBD (Q1 2026)	Database validation
Liveness Check	BWP 2-4	Anti-spoofing verification
Face Match	BWP 1-2	Compare two faces

Contact [email protected] for volume discounts.

Support

• Email: [email protected]
• API Reference: Full API Docs
• Examples: Integration Guides

---

Related Documentation:

• Liveness Detection
• Document Processing
• Customer Onboarding Use Case