Getting Started

Copy page

Quick Start Guide

Get up and running with BotsKYC in minutes.

Prerequisites

• API key from portal.botskyc.com (coming soon) or contact [email protected]
• A REST client (curl, Postman) or your application
• Test documents (sample ID front/back, selfie)

Base URL

Code
 
https://api.botskyc.com

All API requests go through our API gateway at api.botskyc.com.

Authentication

Include your API key in the Authorization header:

Code
 
Authorization: Bearer YOUR_API_KEY

See the Authentication Guide for detailed setup.

Your First API Call

1. Verify an Identity Document

Extract data from an Omang, Passport, or Driver's License:

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"
  },
  "confidence": 98.5,
  "documentType": "OMANG",
  "verificationType": "IDENTITY"
}

2. Verify Address Proof

Extract address information from utility bills or lease agreements:

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"
  },
  "confidence": 96.2,
  "documentType": "UTILITY_BILL",
  "verificationType": "ADDRESS"
}

3. Liveness Detection

Verify that a user is physically present (prevents photo/video spoofing):

Step 1: Create Session

Code
 
curl -X POST https://api.botskyc.com/v1/liveness/session \
  -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"
}

Step 2: Get Results

After user completes liveness check in your frontend:

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

Response:

Code
 
{
  "sessionId": "abc123-def456-ghi789",
  "status": "SUCCEEDED",
  "confidence": 99.5,
  "isLive": true,
  "referenceImage": "base64-encoded-image...",
  "timestamp": "2025-11-24T12:32:00Z"
}

Testing with Postman

1. Download our Postman Collection
2. Import into Postman
3. Set your API key in collection variables
4. Start testing endpoints

Response Codes

Code	Status	Meaning
200	Success	Request completed successfully
400	Bad Request	Invalid input or malformed request
401	Unauthorized	Invalid or missing API key
404	Not Found	Resource not found
422	Unprocessable	Validation failed (e.g., low confidence)
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal error - contact support

Rate Limits

Different tiers have different rate limits:

• Free Tier: 100 requests/day
• Starter: 1,000 requests/day
• Professional: 10,000 requests/day
• Enterprise: Custom limits

When rate limited, you'll receive a 429 response with a Retry-After header.

Next Steps

• Authentication Guide - Get your API credentials
• API Reference - Explore all available endpoints
• Integration Guides - Code examples in JavaScript, Python
• Error Handling - Handle errors gracefully
• Use Cases - Common implementation patterns

Need Help?

• Email: [email protected]
• API Reference: developers.botskyc.com/api
• GitHub: Sample code and SDKs (coming soon)

Sample Documents

For testing, you can use the sample documents in our test-documents repository.