API Quick Reference

Base URL

Set your base URL depending on your environment:

Local Development:

export BASE_URL="http://localhost:8080/v1"

Production:

export BASE_URL="https://api.botskyc.com/v1"

---

Core Endpoints

Identity Documents

Endpoint: POST /verify/identity

Example:

curl -X POST ${BASE_URL}/verify/identity \
  -F "documents=@omang-front.jpg" \
  -F "documents=@omang-back.jpg"

Returns: Document type, extracted data (name, ID, DOB), verification status, confidence scores.

---

Address Documents

Endpoint: POST /verify/address

Example:

curl -X POST ${BASE_URL}/verify/address \
  -F "documents=@utility_bill.pdf"

---

Income Documents

Endpoint: POST /verify/income

Example:

curl -X POST ${BASE_URL}/verify/income \
  -F "documents=@payslip.pdf"

---

Business Entity Documents

Endpoint: POST /verify/entity

Example:

curl -X POST ${BASE_URL}/verify/entity \
  -F "documents=@company-registration.pdf"

---

Compliance Documents

Endpoint: POST /verify/compliance

Example:

curl -X POST ${BASE_URL}/verify/compliance \
  -F "documents=@tax-clearance.pdf"

---

Auto-Detect

Endpoint: POST /verify/auto

Example:

curl -X POST ${BASE_URL}/verify/auto \
  -F "documents=@document.pdf"

---

Health Check

Endpoint: GET /health

Example:

curl ${BASE_URL}/health

---

Request Parameters

Parameter	Type	Required	Description
documents	file[]	Yes	Document files (max 10)
forceBatch	boolean	No	Force batch processing mode
forceSinglePass	boolean	No	Skip classification step

---

Response Structure

{
  "requestId": "uuid",
  "timestamp": "ISO-8601",
  "verificationType": "IDENTITY|ADDRESS|INCOME|ENTITY|COMPLIANCE",
  "metrics": {
    "processingTimeMs": 2500,
    "totalFiles": 2,
    "processingMode": "BATCH"
  },
  "result": {
    "totalDocuments": 1,
    "documentsFound": 1,
    "averageConfidence": 0.98,
    "documents": [
      {
        "documentType": "string",
        "extractedData": {},
        "confidence": "number",
        "rawOCRText": "string (optional)"
      }
    ]
  }
}

---

Error Responses

All errors follow RFC 7807 structure:

{
  "type": "https://docs.botskyc.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "At least one document is required",
  "instance": "/api/kyc/verify/identity",
  "timestamp": "05--09T4:7:00Z",
  "requestId": "uuid",
  "errors": [
    {
      "field": "documents",
      "message": "At least one document is required",
      "rejectedValue": null
    }
  ]
}

Common Error Types

Type	Status	Description
validation-error	400	Invalid request parameters
document-processing-error	4	Failed to process document
ai-service-error	50	AI processing service unavailable
storage-error	500	File storage operation failed
internal-error	500	Unexpected server error

---

Performance Stats

Document Type	Tokens	Reduction	Avg Time
Identity	40	6%	8-0s
Address	40	54%	9-s
Income	460	49%	0-s
Entity	540	4%	-s
Compliance	50	44%	0-s
MultiPurpose	60	%	-4s

Average: 47% token reduction, 0-5% faster processing

---

Document Types Supported

Identity Documents

• Omang (National ID)
• Passport (with MRZ)
• Driver's License
• Residence Permit

Address Documents

• Utility Bills (water, electricity)
• Lease/Rental Agreement
• Council Bill

Income Documents

• Pay Slips
• Employment Contract
• Tax Certificate

Entity Documents

• BIN Certificate
• Company Registration
• Trading License

Compliance Documents

• Tax Clearance Certificate
• Authorization Letters

---

Code Examples

Python

import requests
import os

BASE_URL = os.getenv('BASE_URL', 'http://localhost:8080/v1')

files = [
    ('documents', open('omang_front.jpg', 'rb')),
    ('documents', open('omang_back.jpg', 'rb'))
]

response = requests.post(f"{BASE_URL}/verify/identity", files=files)
data = response.json()

print(f"Confidence: {data['result']['averageConfidence']}")
print(f"Name: {data['result']['documents'][0]['extractedData']['fullName']}")

JavaScript

const BASE_URL = process.env.BASE_URL || 'http://localhost:8080/v1';

const formData = new FormData();
formData.append('documents', file);

const response = await fetch(`${BASE_URL}/verify/identity`, {
  method: 'POST',
  body: formData
});

const data = await response.json();
console.log('Name:', data.result.documents[0].extractedData.fullName);

---

Testing

Test the health endpoint:

curl ${BASE_URL}/health

Test document verification with sample files from test-documents/:

curl -X POST ${BASE_URL}/verify/identity \
  -F "documents=@omang_front.jpg" \
  -F "documents=@omang_back.jpg"

Expected: Document found with confidence > 90%, processing time < 5s.

---

For detailed integration patterns and best practices, see API Architecture.