API Documentation | AI-Powered KYC & Fraud Detection

Getting Started

OpenKYC Africa provides AI-powered identity verification for African businesses. Our API lets you verify users through document verification, face matching, and liveness detection.

Base URL

https://api.openkyc.africa

Mini App URL

Users complete verification through our Telegram Mini App:

https://app.openkyc.africa?session_id={session_id}

Quick Integration Most integrations only need 2 API calls: Create a session, then check status or receive a webhook when complete.

Authentication

Authenticate API requests by including your API key in the header:

X-API-Key: your-api-key

You can also pass it as a query parameter:

https://api.openkyc.africa/session/create?api_key=your-api-key

Security Note Never expose your API key in client-side code. Always make API calls from your backend server.

Integration Flow

Here's how a typical integration works:

Create Session

Your backend calls our API

→

Redirect User

Send user to Mini App URL

→

User Verifies

User completes KYC flow

→

Receive Webhook

Get notified of result

Example Integration (Python)

import requests

# 1. Create a KYC session
response = requests.post(
    "https://api.openkyc.africa/session/create",
    headers={"X-API-Key": "your-api-key"},
    json={
        "telegram_id": "123456789",
        "username": "johndoe",
        "first_name": "John",
        "last_name": "Doe",
        "webhook_url": "https://yoursite.com/webhooks/kyc",
        "callback_url": "https://yoursite.com/kyc/complete"
    }
)

data = response.json()
session_id = data["session_id"]
mini_app_url = data["mini_app_url"]

# 2. Redirect user to mini_app_url to complete KYC
# User completes verification in the Mini App

# 3. Receive webhook when verification is complete
# Or poll the status endpoint:
status = requests.get(
    f"https://api.openkyc.africa/session/{session_id}/status"
).json()

if status["status"] == "approved":
    print("User verified!")
            

Sessions

Create Session

POST /session/create

Create a new KYC verification session. The session ID is used to track the user through the verification process.

Parameter	Type	Required	Description
`telegram_id`	string	Required	User's Telegram ID or your unique user identifier
`username`	string	Optional	User's Telegram username (without @)
`first_name`	string	Optional	User's first name
`last_name`	string	Optional	User's last name
`email`	string	Optional	User's email address
`phone`	string	Optional	User's phone number
`country_code`	string	Optional	ISO 3166-1 alpha-2 country code (e.g., "ZW", "ZA")
`webhook_url`	string	Optional	URL to receive webhook notifications when KYC status changes
`callback_url`	string	Optional	URL to redirect user after completing KYC
`external_user_id`	string	Optional	Your internal user ID for reference
`metadata`	object	Optional	Custom metadata to store with the session

Response

{
    "session_id": "de01f9bc-dbcc-435d-9b74-8981eff729be",
    "status": "pending",
    "current_step": "personal_info",
    "expires_at": "2026-01-20T12:00:00Z",
    "mini_app_url": "https://app.openkyc.africa?session_id=de01f9bc-dbcc-435d-9b74-8981eff729be",
    "verification_url": "https://app.openkyc.africa?session_id=de01f9bc-dbcc-435d-9b74-8981eff729be",
    "message": "Session created successfully"
}
            

Existing Sessions If a user already has an active session (pending/in_progress), the API returns the existing session instead of creating a new one.

Get Session Status

GET /session/{session_id}/status

Check the current status of a verification session.

Response

{
    "id": "de01f9bc-dbcc-435d-9b74-8981eff729be",
    "status": "approved",
    "current_step": "complete",
    "created_at": "2026-01-19T12:00:00Z",
    "completed_at": "2026-01-19T12:15:00Z",
    "verification": {
        "face_match_score": 0.95,
        "face_match_result": true,
        "liveness_score": 0.98,
        "liveness_result": true,
        "document_valid": true,
        "overall_score": 0.96,
        "fraud_score": 0.05,
        "fraud_risk_level": "low"
    }
}
            

Session Status Values

Status	Description
`pending`	Session created, waiting for user to start
`in_progress`	User is completing verification steps
`pending_review`	Documents submitted, awaiting review
`approved`	Verification successful
`rejected`	Verification failed
`expired`	Session expired (24 hours)

Document Upload

Upload Document

POST /upload/{doc_type}

Upload a verification document. Documents should be sent as base64-encoded images or multipart form data.

Document Types

Type	Description
`selfie`	User's selfie photo
`liveness`	Liveness check video/image
`id_front`	Front of ID document
`id_back`	Back of ID document
`address`	Proof of address document

Verification

Trigger Verification

POST /verify/{session_id}

Trigger AI verification after all required documents are uploaded. This runs face matching, liveness detection, document OCR, and fraud checks.

Response

{
    "status": "approved",
    "overall_score": 0.95,
    "face_match": true,
    "face_score": 0.98,
    "liveness_passed": true,
    "liveness_score": 0.97,
    "document_valid": true,
    "ocr_data": {
        "full_name": "John Doe",
        "id_number": "12-345678-A-90",
        "date_of_birth": "1990-01-15",
        "nationality": "Zimbabwe"
    },
    "fraud_risk_level": "low",
    "fraud_score": 0.05
}
            

User Data

Get User

GET /user/{telegram_id}

Get user information and verification status by Telegram ID.

Webhooks

Webhooks notify your server in real-time when verification status changes. Configure your webhook_url when creating a session.

Webhook Events

Event	Description
`verification.approved`	User successfully verified
`verification.rejected`	Verification failed
`verification.completed`	Verification process finished (check status for result)
`fraud.detected`	Fraud detected during verification

Webhook Payload

{
    "event": "verification.approved",
    "timestamp": "2026-01-19T12:15:00Z",
    "data": {
        "session_id": "de01f9bc-dbcc-435d-9b74-8981eff729be",
        "user_id": "123456789",
        "user_data": {
            "telegram_id": "123456789",
            "username": "johndoe",
            "legal_name": "John Doe",
            "email": "john@example.com",
            "nationality": "Zimbabwe"
        },
        "approved_at": "2026-01-19T12:15:00Z"
    }
}
            

Webhook Headers

Header	Description
`Content-Type`	application/json
`X-KYC-Event`	The event type (e.g., verification.approved)
`X-KYC-Signature`	HMAC-SHA256 signature for verification
`X-KYC-Timestamp`	Timestamp of the webhook

Webhook Security

Verify webhook authenticity using the X-KYC-Signature header:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    """Verify OpenKYC webhook signature"""
    if signature.startswith("sha256="):
        signature = signature[7:]

    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected.lower(), signature.lower())

# In your webhook handler:
if verify_webhook(request.body, request.headers['X-KYC-Signature'], WEBHOOK_SECRET):
    # Valid webhook - process it
    data = json.loads(request.body)
    if data['event'] == 'verification.approved':
        user_id = data['data']['user_id']
        # Update user status in your database
            

Error Handling

The API returns standard HTTP status codes with JSON error details:

Code	Meaning	Description
`200`	Success	Request completed successfully
`400`	Bad Request	Invalid parameters - check the error message
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	User or IP blocked (fraud detection)
`404`	Not Found	Session or resource not found
`429`	Rate Limited	Too many requests - slow down
`500`	Server Error	Internal error - contact support

Error Response Format

{
    "error": "Session not found",
    "code": "SESSION_NOT_FOUND",
    "details": {
        "session_id": "invalid-session-id"
    }
}
            

Testing

Use these endpoints to test your integration:

Health Check GET https://api.openkyc.africa/health - Returns {"status": "healthy"} if API is running.

Test Flow

Create a test session with your API key
Open the mini_app_url in a browser
Complete the verification steps
Check your webhook endpoint receives the notification
Query the session status to confirm

Need Help? Contact us at support@openkyc.africa or visit our contact page.