Liveness Detection

Advanced biometric liveness verification to ensure the person being verified is physically present and prevent spoofing attacks including photos, videos, screen replays, masks, and synthetic faces.

Overview

Liveness detection validates that a user is physically present during verification, providing robust anti-spoofing protection. It can be combined with face matching to compare the live selfie against a reference image from an ID document.

Key Features

Real-time Verification - Results in under seconds
High Accuracy - 99.5%+ confidence scores
Anti-Spoofing - Detects photos, videos, masks, and deepfakes
Face Matching - Compare live selfie with ID photo (90%+ similarity threshold)
Session-Based Flow - Secure one-time tokens with expiration
Quality Metrics - Brightness, sharpness, and pose validation
Combined KYC - Single endpoint for document + liveness verification

How It Works

API Endpoints

1. Create Liveness Session

Create a new face liveness verification session.

POST /api/liveness/session

Request:

{
  "settings": {
    "auditImagesLimit": 4
  }
}

Response:

{
  "sessionId": "abc123-def456-ghi789",
  "status": "CREATED",
  "createdAt": "2025-11-10T12:30:00Z",
  "expiryDate": "2025-11-10T12:40:00Z"
}

Example:

curl -X POST https://api.botskyc.com/api/liveness/session \
  -H "Content-Type: application/json" \
  -d '{"settings": {"auditImagesLimit": 4}}'

---

2. Get Session Results

Retrieve liveness verification results for a completed session.

GET /api/liveness/session/:sessionId/results

Response:

{
  "sessionId": "abc123-def456-ghi789",
  "status": "SUCCEEDED",
  "confidence": 99.5,
  "isLive": true,
  "referenceImage": "base64-encoded-image...",
  "auditImages": ["base64-image-1...", "base64-image-2..."],
  "timestamp": "2025-11-10T12:32:00Z",
  "message": "Liveness verified with 99.50% confidence"
}

Response Fields:

• sessionId - Unique session identifier
• confidence - Confidence score (0-100) that person is live
• isLive - Boolean indicating if liveness check passed
• status - SUCCEEDED, FAILED, IN_PROGRESS
• referenceImage - Base64-encoded face image from verification
• auditImages - Additional verification images
• timestamp - Result generation time

Example:

curl https://api.botskyc.com/api/liveness/session/abc123-def456-ghi789/results

---

3. Verify Liveness (with validation)

Verify liveness with additional validation checks.

POST /api/liveness/verify/:sessionId

Response:

{
  "sessionId": "abc123-def456-ghi789",
  "confidence": 99.5,
  "isLive": true
}

---

4. Compare Faces

Compare a live selfie with an ID document photo.

POST /api/liveness/compare-faces

Request:

{
  "sourceImage": "base64-encoded-id-photo...",
  "targetImage": "base64-encoded-selfie..."
}

Response:

{
  "similarity": 95.,
  "isMatch": true,
  "confidence": 95.,
  "threshold": 90.0
}

Response Fields:

• similarity - Similarity score (0-100) between faces
• isMatch - True if similarity exceeds threshold
• confidence - Confidence in the match
• threshold - Minimum similarity required (default: 90.0)

Example:

curl -X POST https://api.botskyc.com/api/liveness/compare-faces \
  -H "Content-Type: application/json" \
  -d '{
    "sourceImage": "data:image/jpeg;base64,/9j/4AAQ...",
    "targetImage": "data:image/jpeg;base64,/9j/4AAQ..."
  }'

---

5. Combined KYC + Liveness

Perform identity document verification and liveness check in a single request.

POST /api/kyc/analyze/identity-with-liveness

Request (multipart/form-data):

files: [id_front.jpg, id_back.jpg]
liveness_session_id: abc-def456-ghi789

Response:

{
  "kycAnalysis": {
    "totalDocuments": 2,
    "extractedData": {
      "name": "John Doe",
      "idNumber": "123456789",
      "dateOfBirth": "1990-01-15"
    }
  },
  "livenessVerification": {
    "isLive": true,
    "confidence": 99.5
  },
  "faceMatchResult": {
    "isMatch": true,
    "similarity": 95.
  },
  "overallSuccess": true,
  "message": "KYC verification successful. Documents: 2, Liveness: 99.50%, Face Match: ✓"
}

Example:

curl -X POST https://api.botskyc.com/api/kyc/analyze/identity-with-liveness \
  -F "files=@id_front.jpg" \
  -F "files=@id_back.jpg" \
  -F "liveness_session_id=abc123-def456-ghi789"

Frontend Integration

React Example with AWS Amplify UI

import { FaceLivenessDetector } from '@aws-amplify/ui-react-liveness';
import { Amplify } from 'aws-amplify';

function LivenessCheck() {
  const [sessionId, setSessionId] = useState(null);

  // 1. Create session
  useEffect(() => {
    fetch('/api/liveness/session', { method: 'POST' })
      .then(res => res.json())
      .then(data => setSessionId(data.sessionId));
  }, []);

  // 2. Handle liveness check completion
  const handleAnalysisComplete = async () => {
    const results = await fetch(`/api/liveness/session/${sessionId}/results`)
      .then(res => res.json());
    
    if (results.isLive) {
      console.log('Liveness verified!', results.confidence);
    }
  };

  return (
    <div>
      {sessionId && (
        <FaceLivenessDetector
          sessionId={sessionId}
          onAnalysisComplete={handleAnalysisComplete}
        />
      )}
    </div>
  );
}

TypeScript API Service

// services/api.ts
export async function createLivenessSession() {
  const response = await fetch('/api/liveness/session', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' }
  });
  return response.json();
}

export async function verifyLiveness(sessionId: string) {
  const response = await fetch(`/api/liveness/verify/${sessionId}`, {
    method: 'POST'
  });
  return response.json();
}

export async function analyzeDocumentsWithLiveness(
  files: File[], 
  sessionId: string
) {
  const formData = new FormData();
  files.forEach(file => formData.append('files', file));
  formData.append('liveness_session_id', sessionId);

  const response = await fetch('/api/kyc/analyze/identity-with-liveness', {
    method: 'POST',
    body: formData
  });
  return response.json();
}

Error Handling

Common Error Codes

Code	Status	Message	Resolution
1006	500	Liveness session creation failed	Retry or check AWS configuration
1007	400	Liveness session expired	Create a new session
1008	404	Liveness session not found	Verify session ID
1009	422	Liveness confidence too low	Improve lighting/conditions
1010	500	Face matching failed	Check image quality
1011	422	Face similarity too low	Verify same person in both images
5001	503	Liveness service error	Verification engine temporarily unavailable

Error Response Example

{
  "errorCode": 1009,
  "message": "Liveness confidence 85.00% is below required threshold 90.00%",
  "status": 422,
  "timestamp": "2025-11-10T12:35:00Z"
}

Best Practices

Security

• Validate sessions server-side
• Enforce one-time use of session IDs
• Use HTTPS for all requests
• Implement rate limiting
• Don't persist biometric data longer than necessary

User Experience

• Provide clear instructions for users
• Ensure good lighting conditions
• Handle session expiration gracefully
• Show confidence scores to users
• Allow retries on low confidence

Performance

• Set reasonable timeouts (10 minutes default)
• Retry only on transient errors
• Optimize image sizes before upload
• Use audit images for debugging

Configuration

Thresholds

You can configure confidence thresholds for your use case:

• Liveness Confidence - Minimum confidence for liveness check (default: 90%)
• Face Match Threshold - Minimum similarity for face matching (default: 90%)

Troubleshooting

Session Not Found

Problem: Session ID returns 404
Solution: Session may have expired (default 10 minutes). Create a new session.

Low Confidence Score

Problem: Confidence below 90%
Solution:

• Improve lighting conditions
• Ensure face is unobstructed
• Remove glasses or hats
• Position face in center of frame

Face Match Failed

Problem: Similarity score below threshold
Solution:

• Verify same person in both images
• Check image quality and resolution
• Ensure face is clearly visible
• Try different lighting conditions

Service Unavailable

Problem: 503 error from liveness service
Solution:

• Check service status
• Verify API connectivity
• Contact support if issue persists

Support

For additional assistance:

• Email: support@botskyc.com
• Documentation: API Reference
• 🔧 Setup Guide: Verification Engine Configuration