Services

Copy page

Business Verification

Verify business registration and company documents including BIN certificates, company registration, and memorandums.

Overview

The Business Verification service provides comprehensive business entity document processing with AI-powered data extraction from company registration documents.

Base Path: /v1/business

Available Endpoints

Business Scan - Extract Company Details

Extract structured data from business registration documents including company name, registration number, directors, and incorporation details.

Endpoint: POST /v1/business/scan

What it does:

• Extracts company name, BIN, registration number
• Identifies directors and shareholders
• Captures registration date and business type
• Multi-document correlation

Supported Documents:

• BIN Certificate (Business Identification Number)
• Memorandum of Association
• Company Registration Certificate
• Certificate of Incorporation
• Business License
• CIPA Company Profile

Request:

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

Response:

Code
 
{
  "status": "success",
  "totalDocuments": 2,
  "processingTime": "3.2s",
  "extractedData": {
    "companyName": "ABC Trading (Pty) Ltd",
    "binNumber": "BIN123456789",
    "registrationNumber": "REG-2010-1234",
    "registrationDate": "2010-05-15",
    "directors": ["John Doe", "Jane Smith"],
    "shareholders": ["John Doe", "Jane Smith"],
    "businessType": "Private Company",
    "registeredAddress": "123 Main Street, Gaborone",
    "authorizedCapital": "BWP 100,000"
  },
  "confidence": 95.5,
  "documentType": "BIN_CERTIFICATE",
  "verificationType": "ENTITY"
}

Use Cases:

• Business account opening
• Vendor onboarding
• Supplier verification
• Contract due diligence
• Corporate KYC compliance

Pricing: BWP 5-8 per scan

---

Business Verify - Validate Against CIPA Registry

Validate extracted business data against the CIPA (Companies and Intellectual Property Authority) registry.

Endpoint: POST /v1/business/verify

What it does:

• Verifies company exists in CIPA registry
• Confirms registration details match official records
• Checks company status (Active, Dissolved, Suspended)
• Validates directors and shareholders
• Verifies ID numbers using Omang validation

Request:

Code
 
curl -X POST https://api.botskyc.com/v1/business/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "registrationNumber": "BW00001234567",
    "entityName": "ABC Trading (Pty) Ltd",
    "directors": [
      {
        "name": "John Doe",
        "idNumber": "123456789",
        "idType": "OMANG",
        "nationality": "Botswana"
      }
    ],
    "shareholders": [
      {
        "name": "John Doe",
        "idNumber": "123456789",
        "idType": "OMANG",
        "percentage": 100,
        "numberOfShares": 1000,
        "nationality": "Botswana"
      }
    ]
  }'

Response:

Code
 
{
  "status": "VERIFIED",
  "message": "Company verified against CIPA registry",
  "processingTimeMs": 35200,
  "verificationDetails": {
    "companyMatch": true,
    "directorsVerified": true,
    "shareholdersVerified": true
  }
}

Verification Statuses:

Status	Meaning
VERIFIED	All details confirmed against CIPA
PARTIAL	Some details could not be verified
FAILED	Significant mismatches found

---

Business Verify Upload - Scan + Verify in One Call

Upload a business registration PDF and automatically extract data then verify against CIPA.

Endpoint: POST /v1/business/verify/upload

Request:

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

This endpoint combines batch scanning and CIPA verification in a single call — it extracts the registration number from the document and verifies it automatically.

---

Guided Document Scan

Scan a single business document with type validation and use-case tracking.

Endpoint: POST /v1/business/scan/document

Request:

Code
 
curl -X POST https://api.botskyc.com/v1/business/scan/document \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "documentType=BIN_CERTIFICATE" \
  -F "useCase=BANK_ACCOUNT_OPENING"

Optional Parameters:

Param	Type	Description
documentType	string	Expected type: BIN_CERTIFICATE, MEMORANDUM, etc.
useCase	string	Use case for compliance tracking
requiredFields	string	Comma-separated required fields

---

Batch Document Scan

Extract multiple documents from a combined PDF (e.g., a scanned pack of business registration documents).

Endpoint: POST /v1/business/scan/batch

Request:

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

Response includes:

• Array of all documents found with types and extracted data
• Entity profile (consolidated company information)
• Directors register
• Shareholder register
• Compliance tracking (if useCase provided)

---

CIPA Search - Search Business Registry

Search the Botswana CIPA registry for businesses by name.

Endpoint: GET /v1/cipa/search

Request:

Code
 
curl "https://api.botskyc.com/v1/cipa/search?query=ABC%20Trading" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters:

Param	Type	Required	Description
query	string	✅	Business name to search (min 2 chars)
limit	integer	❌	Max results (default: 10)

Response:

Code
 
{
  "success": true,
  "query": "ABC Trading",
  "count": 3,
  "data": [
    {
      "name": "ABC Trading (Pty) Ltd",
      "uin": "BW00001234567",
      "status": "Registered",
      "companyType": "Private Company",
      "isActive": true
    }
  ]
}

---

CIPA Company Details - Get by UIN

Get detailed company information from CIPA registry by Unique Identification Number.

Endpoint: GET /v1/cipa/company/{uin}

Request:

Code
 
curl "https://api.botskyc.com/v1/cipa/company/BW00001234567" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

Code
 
{
  "success": true,
  "uin": "BW00001234567",
  "data": {
    "generalDetails": {
      "companyName": "ABC Trading (Pty) Ltd",
      "companyType": "Private Company",
      "uin": "BW00001234567",
      "companyStatus": "Registered",
      "incorporationDate": "2010-05-15"
    },
    "addresses": {
      "registeredOfficeAddress": "123 Main Street, Gaborone",
      "postalAddress": "P.O. Box 1234, Gaborone",
      "principalPlaceOfBusiness": "123 Main Street, Gaborone"
    },
    "directors": [
      {
        "name": "John Doe",
        "nationality": "Motswana",
        "appointmentDate": "2010-05-15"
      }
    ],
    "shareholders": [
      {
        "name": "John Doe",
        "type": "Individual",
        "nationality": "Motswana"
      }
    ],
    "shareAllocations": [
      {
        "shareholderName": "John Doe",
        "numberOfShares": 1000,
        "percentage": 100
      }
    ],
    "beneficialOwners": [
      {
        "name": "John Doe",
        "entityType": "Individual",
        "percentageOwned": 100
      }
    ]
  }
}

---

Use Cases - Get Requirements

Get document requirements for a specific business verification use case.

Endpoint: GET /v1/business/use-cases

Request:

Code
 
curl "https://api.botskyc.com/v1/business/use-cases" \
  -H "Authorization: Bearer YOUR_API_KEY"

To get requirements for a specific use case:

Code
 
curl "https://api.botskyc.com/v1/business/requirements?useCase=BANK_ACCOUNT_OPENING" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Multi-Document Processing

Business verification often requires multiple documents. The system can process and correlate information across documents:

Example: Complete Business Verification

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

The system will:

1. Extract data from each document
2. Correlate information across documents
3. Validate consistency
4. Return consolidated company information

---

Extracted Data Fields

Company Information

• Company name (legal name)
• Trading name (if different)
• BIN (Business Identification Number)
• Company registration number
• Registration date
• Business type (Pty Ltd, Ltd, Partnership, etc.)
• Incorporation country

Directors & Shareholders

• Full names
• Nationality
• ID/Passport numbers (if available)
• Shareholding percentages
• Appointment dates

Business Details

• Registered address
• Physical address
• Postal address
• Authorized capital
• Issued capital
• Nature of business
• Industry classification

Compliance

• Tax clearance status (if included)
• License numbers
• Regulatory approvals
• Expiry dates

---

Best Practices

Document Quality

For optimal results:

• Clear, legible text - all text readable
• Complete documents - include all pages
• Official documents - use certified copies when possible
• Recent documents - within last 12 months preferred
• High resolution - minimum 1200x800 pixels

Multi-Document Strategy

Submit related documents together for better correlation:

Code
 
// Good: Submit all business docs together
const formData = new FormData();
formData.append('documents', binCertificate);
formData.append('documents', memorandum);
formData.append('documents', companyProfile);

await scanBusiness(formData);

Error Handling

Handle different scenarios appropriately:

Code
 
const response = await scanBusiness(documents);

if (response.confidence < 75) {
  // Low confidence - request better quality documents
  alert('Document quality insufficient. Please provide clearer copies.');
} else if (!response.extractedData.binNumber) {
  // Missing critical information
  alert('BIN number not found. Please include BIN certificate.');
} else if (response.extractedData.registrationDate < '2000-01-01') {
  // Data validation
  await flagForReview('Unusual registration date');
} else {
  // Proceed with verification
  await processBusinessData(response.extractedData);
}

---

Integration Examples

JavaScript

Code
 
async function scanBusiness(files) {
  const formData = new FormData();
  
  // Add multiple files
  files.forEach(file => {
    formData.append('documents', file);
  });
  
  const response = await fetch('https://api.botskyc.com/v1/business/scan', {
    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 scanBusiness([binCert, memorandum]);
console.log('Company:', result.extractedData.companyName);
console.log('Directors:', result.extractedData.directors);

Python

Code
 
import requests
import os

def scan_business(file_paths):
    api_key = os.getenv('BOTSKYC_API_KEY')
    
    files = []
    for path in file_paths:
        files.append(('documents', open(path, 'rb')))
    
    response = requests.post(
        'https://api.botskyc.com/v1/business/scan',
        headers={'Authorization': f'Bearer {api_key}'},
        files=files
    )
    
    response.raise_for_status()
    return response.json()

# Usage
result = scan_business([
    'bin-certificate.pdf',
    'memorandum.pdf'
])

print(f"Company: {result['extractedData']['companyName']}")
print(f"BIN: {result['extractedData']['binNumber']}")

TypeScript

Code
 
interface BusinessData {
  companyName: string;
  binNumber: string;
  registrationNumber: string;
  registrationDate: string;
  directors: string[];
  shareholders: string[];
  businessType: string;
  registeredAddress: string;
}

interface BusinessScanResponse {
  status: 'success' | 'error';
  totalDocuments: number;
  extractedData: BusinessData;
  confidence: number;
  documentType: string;
}

async function scanBusiness(files: File[]): Promise<BusinessScanResponse> {
  const formData = new FormData();
  files.forEach(file => formData.append('documents', file));
  
  const response = await fetch('https://api.botskyc.com/v1/business/scan', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.BOTSKYC_API_KEY}`
    },
    body: formData
  });
  
  if (!response.ok) {
    throw new Error(`Business scan failed: ${response.status}`);
  }
  
  return response.json();
}

// Usage with type safety
const result = await scanBusiness([binFile, memorandumFile]);
const companyName: string = result.extractedData.companyName;

---

Validation & Compliance

Pre-Verification Checks

Before sending documents for verification:

Code
 
function validateBusinessDocuments(files) {
  const errors = [];
  
  // Check file count
  if (files.length === 0) {
    errors.push('At least one document required');
  }
  
  // Check file types
  files.forEach(file => {
    const validTypes = ['application/pdf', 'image/jpeg', 'image/png'];
    if (!validTypes.includes(file.type)) {
      errors.push(`Invalid file type: ${file.name}`);
    }
  });
  
  // Check file sizes
  files.forEach(file => {
    if (file.size > 10 * 1024 * 1024) { // 10MB
      errors.push(`File too large: ${file.name}`);
    }
  });
  
  return errors;
}

// Usage
const errors = validateBusinessDocuments(files);
if (errors.length > 0) {
  alert('Validation errors: ' + errors.join(', '));
} else {
  await scanBusiness(files);
}

Post-Extraction Validation

Validate extracted data against business rules:

Code
 
function validateBusinessData(data) {
  const warnings = [];
  
  // Check BIN format (should be 9-13 digits)
  if (!/^\d{9,13}$/.test(data.binNumber)) {
    warnings.push('BIN format may be incorrect');
  }
  
  // Check registration date is reasonable
  const regDate = new Date(data.registrationDate);
  if (regDate > new Date()) {
    warnings.push('Registration date is in the future');
  }
  
  // Check directors present
  if (!data.directors || data.directors.length === 0) {
    warnings.push('No directors found');
  }
  
  return warnings;
}

---

Response Format

Code
 
interface BusinessScanResponse {
  status: "success" | "error";
  totalDocuments: number;
  processingTime?: string;
  extractedData: {
    companyName: string;
    binNumber: string;
    registrationNumber: string;
    registrationDate: string;
    directors: string[];
    shareholders: string[];
    businessType: string;
    registeredAddress: string;
    authorizedCapital?: string;
    issuedCapital?: string;
    natureOfBusiness?: string;
  };
  confidence: number;
  documentType: string;
  verificationType: string;
  errorCode?: number;
  message?: string;
}

---

Error Codes

Code	Status	Message	Resolution
200	Success	Business documents processed	-
400	Bad Request	Invalid file or parameters	Check file format and request
422	Unprocessable	Low confidence or missing data	Provide clearer documents
500	Server Error	Processing error	Contact support

---

Pricing

Service	Price per Request	Volume Discount
Business Scan	BWP 5-8	Available for 500+ requests/month
Business Verify	BWP 10-15	Available for 500+ requests/month
CIPA Search	BWP 3-5	Available for 500+ requests/month
CIPA Company Details	BWP 5-8	Available for 500+ requests/month

Contact [email protected] for volume pricing.

---

Roadmap

Coming Soon

Enhanced Features

• Financial statement analysis
• Tax compliance verification
• UBO (Ultimate Beneficial Owner) deep analysis
• Cross-border company verification
• Historical company change tracking

---

Support

• Email: [email protected]
• API Reference: Full API Docs
• Sales: [email protected]

---

Related Documentation:

• Document Processing
• Document Forensics
• Risk & Compliance
• Error Handling