eKYC-Onboarder API

Complete API reference for integrating identity verification into your application. Our API enables document verification, face matching, liveness detection, and sanctions screening.

Base URL

http://localhost:9000

Authentication

API Key via X-API-Key header

Content Type

application/json or multipart/form-data

Quick Start

Get started with the eKYC API in three simple steps:

1
Create a Session

Initialize a verification session for your user

2
Submit Documents

Upload ID document and selfie for verification

3
Get Results

Receive verification results via webhook or polling

Authentication

All Partner API endpoints require authentication using an API key. Include your API key in the X-API-Key header with every request.

Example Request Headers 
curl -X POST "http://localhost:9000/partner/sessions" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"external_user_id": "user_123"}'
Getting an API Key

API keys can be created in the Admin Portal under Settings → API Keys. Each key can have specific permissions and rate limits.

Error Handling

The API uses standard HTTP status codes to indicate success or failure of requests.

Status Code Description
200 Success
400 Bad Request - Invalid parameters
401 Unauthorized - Missing or invalid API key
403 Forbidden - Insufficient permissions
404 Not Found - Resource doesn't exist
422 Validation Error - Request body validation failed
500 Internal Server Error
Error Response Format 
{
  "detail": "Session not found",
  "status_code": 404
}

Webhooks

Receive real-time notifications when verification status changes. Configure your webhook URL when creating a session.

Webhook Payload 
{
  "event": "session.completed",
  "session_id": "sess_abc123",
  "status": "approved",
  "risk_level": "low",
  "risk_score": 0.12,
  "timestamp": "2024-01-15T10:30:00Z"
}

Event Types

Event Description
session.created New verification session created
session.document_uploaded ID document uploaded and processed
session.completed Verification completed (approved/rejected/manual_review)
session.expired Session expired before completion
POST

/partner/sessions

Create a new KYC verification session for a user.

Request Body

external_user_id string required
Your unique identifier for the user
webhook_url string
URL to receive status updates
redirect_url string
URL to redirect user after completion
metadata object
Custom key-value data to attach to the session
Request 
curl -X POST "http://localhost:9000/partner/sessions" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user_123",
    "webhook_url": "https://yourapp.com/webhooks/kyc",
    "metadata": {
      "plan": "premium"
    }
  }'
Request 
import requests

response = requests.post(
    "http://localhost:9000/partner/sessions",
    headers={"X-API-Key": "your_api_key"},
    json={
        "external_user_id": "user_123",
        "webhook_url": "https://yourapp.com/webhooks/kyc",
        "metadata": {"plan": "premium"}
    }
)

session = response.json()
print(f"Session ID: {session['session_id']}")
print(f"KYC URL: {session['kyc_url']}")
Request 
const response = await fetch('http://localhost:9000/partner/sessions', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    external_user_id: 'user_123',
    webhook_url: 'https://yourapp.com/webhooks/kyc',
    metadata: { plan: 'premium' }
  })
});

const session = await response.json();
console.log('Session ID:', session.session_id);
console.log('KYC URL:', session.kyc_url);

Response

200 OK 
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "kyc_url": "http://localhost:9000/kyc/550e8400-e29b-41d4-a716-446655440000",
  "expires_at": "2024-01-16T10:30:00Z",
  "created_at": "2024-01-15T10:30:00Z"
}
GET

/partner/sessions/{session_id}

Retrieve the current status and details of a verification session.

Path Parameters

session_id string required
The unique session identifier
Request 
curl -X GET "http://localhost:9000/partner/sessions/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: your_api_key"

Response

200 OK 
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "external_user_id": "user_123",
  "status": "approved",
  "risk_level": "low",
  "risk_score": 0.12,
  "decision": "approved",
  "decision_reason": "All verification checks passed",
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:32:45Z",
  "verification_results": {
    "document_verified": true,
    "face_match_passed": true,
    "face_match_score": 0.94,
    "liveness_passed": true,
    "sanctions_clear": true
  }
}
GET

/partner/sessions

List all verification sessions with optional filtering.

Query Parameters

status string
Filter by status: pending, approved, rejected, manual_review
external_user_id string
Filter by your user ID
limit integer
Number of results (default: 20, max: 100)
offset integer
Number of results to skip
Request 
curl -X GET "http://localhost:9000/partner/sessions?status=approved&limit=10" \
  -H "X-API-Key: your_api_key"
POST

/kyc/{session_id}/document

Upload an identity document for OCR extraction and validation.

Request Body (multipart/form-data)

file file required
Image file (JPEG, PNG) max 10MB
document_type string required
Type: passport, national_id, drivers_license
country_code string required
ISO 3166-1 alpha-2 country code
Request 
curl -X POST "http://localhost:9000/kyc/{session_id}/document" \
  -H "X-API-Key: your_api_key" \
  -F "file=@passport.jpg" \
  -F "document_type=passport" \
  -F "country_code=US"

Response

200 OK 
{
  "document_id": "doc_abc123",
  "document_type": "passport",
  "extraction_confidence": 0.95,
  "full_name": "John Smith",
  "date_of_birth": "1990-05-15",
  "nationality": "USA",
  "document_number_masked": "****1234",
  "expiry_date": "2028-05-15",
  "is_valid": true,
  "mrz_valid": true,
  "validation_errors": []
}
POST

/kyc/{session_id}/selfie

Upload a selfie image to verify face match against the ID document.

Request Body (multipart/form-data)

file file required
Selfie image (JPEG, PNG) max 10MB
Request 
curl -X POST "http://localhost:9000/kyc/{session_id}/selfie" \
  -H "X-API-Key: your_api_key" \
  -F "file=@selfie.jpg"

Response

200 OK 
{
  "verification_id": "ver_xyz789",
  "match_score": 0.94,
  "match_passed": true,
  "confidence": "high"
}
GET

/kyc/{session_id}/liveness/challenge

Get a liveness challenge for the user to complete.

Response 
{
  "challenge_id": "chl_abc123",
  "challenge_type": "head_turn",
  "instructions": "Please turn your head slowly to the left",
  "timeout_seconds": 30
}
POST

/kyc/{session_id}/liveness

Submit video frames for liveness verification.

Request Body (multipart/form-data)

challenge_id string required
The challenge ID from the previous step
files file[] required
Array of video frames (min 5 frames)

Response

200 OK 
{
  "check_id": "lvc_xyz789",
  "passed": true,
  "confidence": 0.92,
  "spoof_detected": false,
  "checks_performed": ["blink", "head_movement", "texture_analysis"]
}
POST

/kyc/{session_id}/submit

Submit the session for final verification, triggering sanctions screening and risk assessment.

Request 
curl -X POST "http://localhost:9000/kyc/{session_id}/submit" \
  -H "X-API-Key: your_api_key"

Response

200 OK 
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "approved",
  "decision": "approved",
  "risk_score": 0.12,
  "risk_level": "low",
  "document_verified": true,
  "face_match_passed": true,
  "liveness_passed": true,
  "screening_passed": true,
  "review_reasons": [],
  "started_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:32:45Z"
}
Decision Outcomes

Sessions may result in approved, rejected, or manual_review. Manual review cases require admin action in the Admin Portal.

GET

/health

Check the health status of the API.

Response 
{
  "status": "healthy",
  "version": "1.0.0",
  "database": "connected"
}

OpenAPI Specification

For the complete API specification, you can also access:

OpenAPI JSON Swagger UI ReDoc