Services

Copy page

Document Processing

Extract structured data from various document types for complete KYC compliance.

Overview

The Document Processing service provides intelligent document analysis across multiple categories including address verification, income verification, and general document scanning.

Base Path: /v1/documents

Available Endpoints

Document Scan - Auto-Detect Any Document

Automatically detect document type and extract relevant data. Routes to specialized extractors based on content analysis.

Endpoint: POST /v1/documents/scan

What it does:

• Auto-detects document type
• Extracts relevant data fields
• Routes to appropriate specialized service
• Returns extracted data with confidence scores

Supported Document Types:

• Address proof (utility bills, lease agreements)
• Income proof (payslips, tax documents)
• Identity documents (Omang, Passport, License)
• Business documents (registration, certificates)

Request:

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

Response:

Code
 
{
  "status": "success",
  "totalDocuments": 1,
  "detectedType": "UTILITY_BILL",
  "routedTo": "AddressVerificationService",
  "extractedData": {
    "name": "John Doe",
    "address": "123 Main Street, Gaborone",
    "accountNumber": "ACC-123456",
    "issueDate": "2025-01-10"
  },
  "confidence": 96.5,
  "documentType": "UTILITY_BILL",
  "verificationType": "ADDRESS"
}

Use Cases:

• Universal document processing
• KYC compliance workflows
• Multi-document batch processing
• Unknown document classification

Pricing: BWP 5-8 per document

---

Address Scan - Extract Address Proof

Extract address information from utility bills, lease agreements, and proof of residence documents.

Endpoint: POST /v1/documents/address/scan

What it does:

• Extracts name, address, issue date
• Supports utility bills, lease agreements, council bills
• Validates address format
• Multi-page PDF support

Supported Documents:

• Utility Bills (Water, Electricity, Internet)
• Lease Agreements
• Landlord Letters
• Council Bills
• Affidavits
• Kgotla Letters

Request:

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

Response:

Code
 
{
  "status": "success",
  "totalDocuments": 1,
  "extractedData": {
    "name": "John Doe",
    "address": "123 Main Street, Gaborone",
    "issueDate": "2025-01-10",
    "accountNumber": "ACC-123456",
    "serviceType": "Electricity",
    "provider": "Botswana Power Corporation"
  },
  "confidence": 96.2,
  "documentType": "UTILITY_BILL",
  "verificationType": "ADDRESS"
}

Use Cases:

• Address verification for banking
• Proof of residence for SIM registration
• Customer onboarding compliance
• Telecom regulatory requirements

Pricing: BWP 5-8 per document

---

Income Scan - Extract Income Proof

Extract salary and income information from payslips, tax documents, and employment contracts.

Endpoint: POST /v1/documents/income/scan

What it does:

• Extracts salary details and deductions
• Calculates net income
• Validates tax calculations
• Multi-month processing support

Supported Documents:

• Pay Slips
• Employment Contracts
• P60 Forms
• Tax Certificates (IT12)
• Proof of Income Letters
• Financial Statements

Request:

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

Response:

Code
 
{
  "status": "success",
  "totalDocuments": 1,
  "extractedData": {
    "employeeName": "John Doe",
    "employer": "ABC Company Ltd",
    "grossSalary": 15000.00,
    "netSalary": 12500.00,
    "payPeriod": "2025-10",
    "taxDeductions": 2500.00,
    "pension": 0.00,
    "otherDeductions": 0.00
  },
  "confidence": 97.8,
  "documentType": "PAYSLIP",
  "verificationType": "INCOME"
}

Use Cases:

• Loan application processing
• Credit assessment
• Employment verification
• Financial underwriting

Pricing: BWP 5-8 per document

---

Fraud Detection

Detect document tampering, forgery, and manipulation.

Endpoint: POST /v1/documents/fraud-detect

Status: Coming Q2 2026

What it will do:

• Detect digital manipulation and editing
• Identify forged signatures
• Analyze document authenticity markers
• Check metadata for tampering signs
• Validate watermarks and security features

---

Multi-Format Support

Supported File Formats

• Images: JPG, JPEG, PNG
• Documents: PDF (single and multi-page)
• Max file size: 10MB per file
• Max files per request: 10 files

Processing Modes

Single Document:

Code
 
-F "[email protected]"

Multiple Documents (Batch):

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

Multi-page PDF: System automatically processes all pages.

---

Best Practices

Image Quality

For optimal results:

• Minimum resolution: 1200x800 pixels
• Clear, legible text without blur
• Good lighting without glare or shadows
• Full document visible - all corners in frame
• Flat surface - avoid curved or wrinkled documents

Document Preparation

• Orientation: Ensure documents are right-side up
• Completeness: Include all pages of multi-page documents
• Clarity: Remove any covers or protective sleeves
• Format: PDF preferred for multi-page documents

Error Handling

Handle different confidence levels appropriately:

Code
 
const response = await scanDocument(file);

if (response.confidence < 70) {
  // Very low confidence - reject
  throw new Error('Document quality too poor. Please upload a clearer image.');
} else if (response.confidence < 85) {
  // Medium confidence - flag for review
  await flagForManualReview(response);
  notifyUser('Document accepted but will be manually reviewed.');
} else {
  // High confidence - auto-approve
  await processDocument(response.extractedData);
}

---

Integration Examples

JavaScript

Code
 
async function scanDocument(file, type = 'scan') {
  const formData = new FormData();
  formData.append('documents', file);
  
  const endpoint = type === 'address' 
    ? '/v1/documents/address/scan'
    : type === 'income'
    ? '/v1/documents/income/scan'
    : '/v1/documents/scan';
  
  const response = await fetch(`https://api.botskyc.com${endpoint}`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.BOTSKYC_API_KEY}`
    },
    body: formData
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }
  
  return response.json();
}

// Usage
const result = await scanDocument(utilityBillFile, 'address');
console.log('Address:', result.extractedData.address);

Python

Code
 
import requests
import os

def scan_document(file_path, doc_type='scan'):
    api_key = os.getenv('BOTSKYC_API_KEY')
    
    endpoints = {
        'scan': '/v1/documents/scan',
        'address': '/v1/documents/address/scan',
        'income': '/v1/documents/income/scan'
    }
    
    endpoint = endpoints.get(doc_type, '/v1/documents/scan')
    
    with open(file_path, 'rb') as f:
        files = {'documents': f}
        response = requests.post(
            f'https://api.botskyc.com{endpoint}',
            headers={'Authorization': f'Bearer {api_key}'},
            files=files
        )
    
    response.raise_for_status()
    return response.json()

# Usage
result = scan_document('utility-bill.pdf', 'address')
print(f"Address: {result['extractedData']['address']}")

Batch Processing

Process multiple documents in one request:

Code
 
async function scanMultipleDocuments(files) {
  const formData = new FormData();
  files.forEach(file => formData.append('documents', file));
  
  const response = await fetch('https://api.botskyc.com/v1/documents/scan', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.BOTSKYC_API_KEY}`
    },
    body: formData
  });
  
  return response.json();
}

// Process 3 documents at once
const results = await scanMultipleDocuments([bill1, bill2, payslip]);

---

Response Format

All document processing endpoints return a consistent response structure:

Code
 
interface DocumentResponse {
  status: "success" | "error";
  totalDocuments: number;
  processingTime?: string;
  detectedType?: string;
  routedTo?: string;
  extractedData: {
    [key: string]: any;  // Document-specific fields
  };
  confidence: number;
  documentType: string;
  verificationType: string;
  errorCode?: number;
  message?: string;
}

---

Error Codes

Code	Status	Message	Resolution
200	Success	Document processed successfully	-
400	Bad Request	Invalid file format or missing fields	Check file format and parameters
422	Unprocessable	Low confidence or validation failed	Improve image quality, retake photo
500	Server Error	Processing error	Contact support

Error Response Example:

Code
 
{
  "status": "error",
  "errorCode": 1004,
  "message": "Document validation failed: Low confidence score",
  "details": {
    "confidence": 65.5,
    "threshold": 80.0,
    "reason": "Poor image quality"
  }
}

---

Pricing

Service	Price per Request	Volume Discount
Document Scan	BWP 5-8	Available for 1000+ requests/month
Address Scan	BWP 5-8	Available for 1000+ requests/month
Income Scan	BWP 5-8	Available for 1000+ requests/month
Fraud Detection	TBD (Q2 2026)	-

Contact [email protected] for volume pricing.

---

Support

• Email: [email protected]
• API Reference: Full API Docs
• Integration Guides: JavaScript, Python

---

Related Documentation:

• Identity Verification
• Business Verification
• Error Handling