Skip to main content

👤🔍 Face Recognition API

Advanced face recognition and detection system powered by AI

Version Status License

Overview

The iApp Face Recognition API is a comprehensive facial recognition solution that provides face detection, recognition, comparison, and database management capabilities. Built on state-of-the-art deep learning models, our API delivers high accuracy and fast processing for various use cases including security, authentication, and identity verification.

Try Demo!

Face Recognition API Demo

Test our face recognition endpoints with real-time results

Endpoint changes based on selected tab

Recognizes the most prominent face in an image and matches it against your company's face database.

Supported: JPG, JPEG, PNG (max 2MB)

Key Features

Core Capabilities

  • Face Detection: Detect single or multiple faces in images with bounding box coordinates
  • Face Recognition: Identify known individuals from your custom face database
  • Face Comparison: Compare two faces to determine if they belong to the same person
  • Database Management: Add, remove, import, and export face records
  • Configurable Thresholds: Customize detection and recognition sensitivity
  • Multi-face Support: Process images containing multiple faces simultaneously

Technical Features

  • High-accuracy face detection (99%+ on frontal faces)
  • Fast processing time (0.3-1.0 seconds typical)
  • Support for various image formats (JPEG, JPG, PNG)
  • Maximum file size: 2MB
  • Company-specific face databases
  • Score-based matching with configurable thresholds
  • RESTful API with simple integration

Getting Started

Prerequisites

  • API Key: Obtain from iApp API Portal
  • Company Account: Register your company for face database management
  • Image Requirements:
    • Formats: JPEG, JPG, PNG
    • Maximum size: 2MB
    • Minimum resolution: 600x400 pixels
    • Minimum face size: 112x112 pixels

Quick Start Example

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/single \
-H "apikey: YOUR_API_KEY" \
-F "file=@photo.jpg" \
-F "company=iApp"
How to get API Key?

Please visit API Key Management page to view your existing API key or request a new one.

API Endpoints

Recognition Endpoints

EndpointMethodDescriptionCost
/v3/store/ekyc/face-recognition/singlePOSTRecognize the most prominent face0.3 IC

| /v3/store/ekyc/face-recognition/multi | POST | Recognize all faces in image | 0.3 IC | | /v3/store/ekyc/face-recognition/add | POST | Add new face to database | 0.1 IC | | /v3/store/ekyc/face-recognition/remove | POST | Remove face from database | 0 IC | | /v3/store/ekyc/face-recognition/check | POST | Check database status | 0.3 IC | | /v3/store/ekyc/face-recognition/import | POST | Import face features (CSV) | 0 IC | | /v3/store/ekyc/face-recognition/export | POST | Export face features | 0 IC |

Detection Endpoints

EndpointMethodDescriptionCost
/v3/store/ekyc/face-detection/singlePOSTDetect single face with bounding box0.3 IC
/v3/store/ekyc/face-detection/multiPOSTDetect all faces in image0.3 IC

Comparison Endpoint

EndpointMethodDescriptionCost
/v3/store/ekyc/face-comparisonPOSTCompare two faces for similarity0.3 IC

Configuration Endpoints

EndpointMethodDescriptionCost
/v3/store/ekyc/face-recognition/configPOSTConfigure detection/recognition thresholds0 IC
/v3/store/ekyc/face-recognition/password/changePOSTChange company password0 IC

Admin Endpoints

EndpointMethodDescriptionCost
/v3/store/ekyc/face-recognition/admin/importPOSTAdmin: Import features0 IC
/v3/store/ekyc/face-recognition/admin/exportPOSTAdmin: Export features0 IC
/v3/store/ekyc/face-recognition/admin/configPOSTAdmin: Configure thresholds0 IC
/v3/store/ekyc/face-recognition/admin/checkPOSTAdmin: Check database0 IC
/v3/store/ekyc/face-recognition/admin/password/changePOSTAdmin: Change password0 IC

API Reference

Recognition Endpoints

Single Face Recognition

Endpoint: POST /v3/store/ekyc/face-recognition/single

Recognizes the most prominent face in an image and matches it against your company's face database.

Request Parameters:

ParameterTypeRequiredDescription
fileFileYesImage file (JPEG, JPG, PNG, max 2MB)
companyStringYesYour company identifier

Response Format:

{
"message": "successfully performed",
"company": "YOUR_COMPANY",
"name": "John Doe",
"recognition_score": 0.8523,
"detection_score": 0.9998,
"bbox": {
"xmin": 154.39,
"ymin": 155.49,
"xmax": 255.45,
"ymax": 282.88
},
"process_time": 0.4776
}

Response Fields:

  • name: Identified person name (or "unknown" if no match)
  • recognition_score: Recognition confidence (0-1)
  • detection_score: Face detection confidence (0-1)
  • bbox: Face bounding box coordinates
  • process_time: Processing time in seconds

Example:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/single \
-H "apikey: YOUR_API_KEY" \
-F "file=@face.jpg" \
-F "company=iApp"

Multi-Face Recognition

Endpoint: POST /v3/store/ekyc/face-recognition/multi

Recognizes all faces in an image, returning an array of results for each detected face.

Request Parameters:

ParameterTypeRequiredDescription
fileFileYesImage file (JPEG, JPG, PNG, max 2MB)
companyStringYesYour company identifier

Response Format:

{
"message": "successfully performed",
"company": "YOUR_COMPANY",
"faces": [
{
"name": "John Doe",
"recognition_score": 0.8523,
"detection_score": 0.9998,
"bbox": {
"xmin": 154.39,
"ymin": 155.49,
"xmax": 255.45,
"ymax": 282.88
}
},
{
"name": "Jane Smith",
"recognition_score": 0.7891,
"detection_score": 0.9995,
"bbox": {
"xmin": 350.12,
"ymin": 180.34,
"xmax": 450.67,
"ymax": 310.23
}
}
],
"process_time": 0.6234
}

Example:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/multi \
-H "apikey: YOUR_API_KEY" \
-F "file=@group_photo.jpg" \
-F "company=iApp"

Add Face to Database

Endpoint: POST /v3/store/ekyc/face-recognition/add

Adds a new face to your company's recognition database. This registers a person for future recognition.

Request Parameters:

ParameterTypeRequiredDescription
fileFileYesClear face image (JPEG, JPG, PNG, max 2MB)
companyStringYesYour company identifier
nameStringYesPerson's name for identification
passwordStringYesCompany password for authentication

Response Format:

{
"message": "successfully performed",
"company": "YOUR_COMPANY",
"name": "John Doe",
"face_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"detection_score": 0.9998
}

Response Fields:

  • face_id: Unique identifier for the added face
  • detection_score: Quality score of the face image
  • name: Registered person name

Example:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/add \
-H "apikey: YOUR_API_KEY" \
-F "file=@john_doe.jpg" \
-F "company=iApp" \
-F "name=John Doe" \
-F "password=iApp"
Demo Password

For the demo company "iApp", the password is "iApp". You can use this to test the Face Recognition API endpoints.

Best Practices:

  • Use clear, frontal face images
  • Ensure good lighting
  • Avoid blurry or low-quality images
  • One face per image
  • Person should be looking at camera

Remove Face from Database

Endpoint: POST /v3/store/ekyc/face-recognition/remove

Removes a face record from your company's database.

Request Parameters:

ParameterTypeRequiredDescription
companyStringYesYour company identifier
nameStringYesPerson's name to remove
passwordStringYesCompany password for authentication
face_idStringNoSpecific face ID to remove (if multiple entries exist)

Response Format:

{
"message": "face removed successfully",
"company": "YOUR_COMPANY",
"name": "John Doe",
"removed_count": 1
}

Example:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/remove \
-H "apikey: YOUR_API_KEY" \
-F "company=iApp" \
-F "name=John Doe" \
-F "password=iApp"

With Specific Face ID:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/remove \
-H "apikey: YOUR_API_KEY" \
-F "company=iApp" \
-F "name=John Doe" \
-F "face_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
-F "password=iApp"

Check Face Database

Endpoint: POST /v3/store/ekyc/face-recognition/check

Checks the status and contents of your company's face database. Returns statistics and optionally exports a report file.

Request Parameters:

ParameterTypeRequiredDescription
companyStringYesYour company identifier
passwordStringYesCompany password for authentication
save_fileStringNoSet to "True" or "1" to export report file

Response Format (Without file export):

{
"message": "successfully performed",
"company": "YOUR_COMPANY",
"total_faces": 145,
"total_persons": 145,
"database_size": "2.3 MB",
"last_updated": "2025-01-15T10:30:00Z"
}

Response Format (With file export):

Returns a CSV file containing the face database report.

Example:

# Get database statistics
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/check \
-H "apikey: YOUR_API_KEY" \
-F "company=iApp" \
-F "password=iApp"

# Export database report
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/check \
-H "apikey: YOUR_API_KEY" \
-F "company=iApp" \
-F "password=iApp" \
-F "save_file=True" \
-o database_report.csv

Import Face Features

Endpoint: POST /v3/store/ekyc/face-recognition/import

Imports pre-computed face features from a CSV file into your company's database. Useful for bulk import or database migration.

Request Parameters:

ParameterTypeRequiredDescription
fileFileYesCSV file containing face features
companyStringYesYour company identifier
passwordStringYesCompany password for authentication

CSV File Format:

The CSV file should contain face feature vectors with columns: name, face_id, feature_vector (comma-separated float values).

Response Format:

{
"message": "successfully performed",
"company": "YOUR_COMPANY",
"imported_count": 50,
"failed_count": 0,
"total_processed": 50
}

Example:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/import \
-H "apikey: YOUR_API_KEY" \
-F "file=@face_features.csv" \
-F "company=iApp" \
-F "password=iApp"

Note: Import is not available for demo accounts.


Export Face Features

Endpoint: POST /v3/store/ekyc/face-recognition/export

Exports face features from your company's database to a file. Supports CSV and Excel formats.

Request Parameters:

ParameterTypeRequiredDescription
companyStringYesYour company identifier
passwordStringYesCompany password for authentication
type_fileStringYesExport format: "csv" or "excel"

Response:

Returns a file download with the exported face features.

Example:

# Export as CSV
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/export \
-H "apikey: YOUR_API_KEY" \
-F "company=iApp" \
-F "password=iApp" \
-F "type_file=csv" \
-o face_features.csv

# Export as Excel
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/export \
-H "apikey: YOUR_API_KEY" \
-F "company=iApp" \
-F "password=iApp" \
-F "type_file=excel" \
-o face_features.xlsx

Note: Export is not available for demo accounts.


Detection Endpoints

Single Face Detection

Endpoint: POST /v3/store/ekyc/face-detection/single

Detects the most prominent face in an image and returns bounding box coordinates without performing recognition.

Request Parameters:

ParameterTypeRequiredDescription
fileFileYesImage file (JPEG, JPG, PNG, max 2MB)
companyStringNoOptional company identifier

Response Format:

{
"message": "successfully performed",
"detection_score": 0.9998,
"bbox": {
"xmin": 154.39,
"ymin": 155.49,
"xmax": 255.45,
"ymax": 282.88
},
"process_time": 0.2134
}

Example:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-detection/single \
-H "apikey: YOUR_API_KEY" \
-F "file=@photo.jpg"

Multi-Face Detection

Endpoint: POST /v3/store/ekyc/face-detection/multi

Detects all faces in an image and returns bounding box coordinates for each face without performing recognition.

Request Parameters:

ParameterTypeRequiredDescription
fileFileYesImage file (JPEG, JPG, PNG, max 2MB)
companyStringNoOptional company identifier

Response Format:

{
"message": "successfully performed",
"faces": [
{
"detection_score": 0.9998,
"bbox": {
"xmin": 154.39,
"ymin": 155.49,
"xmax": 255.45,
"ymax": 282.88
}
},
{
"detection_score": 0.9995,
"bbox": {
"xmin": 350.12,
"ymin": 180.34,
"xmax": 450.67,
"ymax": 310.23
}
}
],
"total_faces": 2,
"process_time": 0.3567
}

Example:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-detection/multi \
-H "apikey: YOUR_API_KEY" \
-F "file=@group_photo.jpg"

Comparison Endpoint

Compare Two Faces

Endpoint: POST /v3/store/ekyc/face-comparison

Compares two face images to determine if they belong to the same person. Returns a similarity score.

Request Parameters:

ParameterTypeRequiredDescription
file1FileYesFirst face image (JPEG, JPG, PNG, max 2MB)
file2FileYesSecond face image (JPEG, JPG, PNG, max 2MB)
companyStringNoOptional company identifier
min_scoreFloatNoMinimum similarity threshold (0-1)

Response Format:

{
"message": "successfully performed",
"status": {
"face1_detected": true,
"face2_detected": true,
"match": true
},
"similarity_score": 0.8734,
"comparison_score": 0.8734,
"face1_bbox": {
"xmin": 154.39,
"ymin": 155.49,
"xmax": 255.45,
"ymax": 282.88
},
"face2_bbox": {
"xmin": 180.23,
"ymin": 170.12,
"xmax": 280.56,
"ymax": 295.34
},
"process_time": 0.5423
}

Response Fields:

  • match: Boolean indicating if faces match (based on threshold)
  • similarity_score: Similarity score between faces (0-1)
  • status: Detection status for both faces
  • face1_bbox, face2_bbox: Bounding boxes for detected faces

Example:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-comparison \
-H "apikey: YOUR_API_KEY" \
-F "file1=@person1.jpg" \
-F "file2=@person2.jpg"

With Minimum Score Threshold:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-comparison \
-H "apikey: YOUR_API_KEY" \
-F "file1=@person1.jpg" \
-F "file2=@person2.jpg" \
-F "min_score=0.8"

Configuration Endpoints

Configure Thresholds

Endpoint: POST /v3/store/ekyc/face-recognition/config

Configures detection and recognition score thresholds for your company. These thresholds determine the minimum confidence scores required for successful face detection and recognition.

Request Parameters:

ParameterTypeRequiredDescription
companyStringYesYour company identifier
passwordStringYesCompany password for authentication
detectionFloatNoDetection threshold (0-100 or 0-1)
comparisonFloatNoComparison threshold (0-100 or 0-1)
recognitionFloatNoRecognition threshold (0-100 or 0-1)

Response Format:

{
"message": "the minimum score of detection, comparison and recognition has been successfully configured.",
"company": "YOUR_COMPANY",
"detection_score": 0.75,
"comparison_score": 0.80,
"recognition_score": 0.85
}

Example:

# Set all thresholds
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/config \
-H "apikey: YOUR_API_KEY" \
-F "company=iApp" \
-F "password=iApp" \
-F "detection=75" \
-F "comparison=80" \
-F "recognition=85"

# Get current thresholds (omit score parameters)
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/config \
-H "apikey: YOUR_API_KEY" \
-F "company=iApp" \
-F "password=iApp"

# Set only recognition threshold
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/config \
-H "apikey: YOUR_API_KEY" \
-F "company=iApp" \
-F "password=iApp" \
-F "recognition=90"

Threshold Guidelines:

  • Detection (default ~0.75): Minimum confidence for face detection

    • Lower: Detect more faces (may include false positives)
    • Higher: Detect only clear faces (may miss some faces)
  • Comparison (default ~0.80): Minimum similarity for face matching

    • Lower: More lenient matching (may match different people)
    • Higher: Stricter matching (may reject same person)
  • Recognition (default ~0.85): Minimum confidence for person identification

    • Lower: More permissive recognition (may misidentify)
    • Higher: More restrictive recognition (may fail to recognize)

Note: Configuration is not available for demo accounts.


Change Password

Endpoint: POST /v3/store/ekyc/face-recognition/password/change

Changes your company's password for API authentication.

Request Parameters:

ParameterTypeRequiredDescription
companyStringYesYour company identifier
old_passwordStringYesCurrent password
new_passwordStringYesNew password (must be different)

Response Format:

{
"message": "Setting new password completed."
}

Example:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/password/change \
-H "apikey: YOUR_API_KEY" \
-F "company=iApp" \
-F "old_password=current_password" \
-F "new_password=new_secure_password"

Note: Password change is not available for demo accounts.


Admin Endpoints

Admin endpoints require special admin privileges and are not available for regular users.

Admin: Import Features

Endpoint: POST /v3/store/ekyc/face-recognition/admin/import

Imports face features into the demo database (admin only).

Request Parameters:

ParameterTypeRequiredDescription
companyStringYesMust be "admin"
passwordStringYesAdmin password
fileFileYesCSV file with face features

Example:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/admin/import \
-H "apikey: YOUR_API_KEY" \
-F "company=admin" \
-F "password=admin_password" \
-F "file=@features.csv"

Admin: Export Features

Endpoint: POST /v3/store/ekyc/face-recognition/admin/export

Exports face features from the demo database or creates a backup (admin only).

Request Parameters:

ParameterTypeRequiredDescription
companyStringYesMust be "admin"
passwordStringYesAdmin password
type_fileStringYesExport format: "csv", "excel", or "backup"

Example:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/admin/export \
-H "apikey: YOUR_API_KEY" \
-F "company=admin" \
-F "password=admin_password" \
-F "type_file=backup" \
-o backup.csv

Admin: Configure Thresholds

Endpoint: POST /v3/store/ekyc/face-recognition/admin/config

Configures score thresholds for admin or demo account (admin only).

Request Parameters:

ParameterTypeRequiredDescription
companyStringYes"admin" or "demo"
passwordStringYesAdmin password
detectionFloatNoDetection threshold (0-100 or 0-1)
comparisonFloatNoComparison threshold (0-100 or 0-1)
recognitionFloatNoRecognition threshold (0-100 or 0-1)

Example:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/admin/config \
-H "apikey: YOUR_API_KEY" \
-F "company=demo" \
-F "password=admin_password" \
-F "detection=70" \
-F "recognition=80"

Admin: Check Database

Endpoint: POST /v3/store/ekyc/face-recognition/admin/check

Checks admin or demo database status (admin only).

Request Parameters:

ParameterTypeRequiredDescription
companyStringYes"admin" or "demo"
passwordStringYesAdmin password
save_fileStringNoSet to "True" or "1" to export report

Example:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/admin/check \
-H "apikey: YOUR_API_KEY" \
-F "company=demo" \
-F "password=admin_password"

Admin: Change Password

Endpoint: POST /v3/store/ekyc/face-recognition/admin/password/change

Changes password for admin or demo account (admin only).

Request Parameters:

ParameterTypeRequiredDescription
companyStringYes"admin" or "demo"
old_passwordStringYesCurrent admin password
new_passwordStringYesNew password (must be different)

Example:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/admin/password/change \
-H "apikey: YOUR_API_KEY" \
-F "company=demo" \
-F "old_password=current_admin_password" \
-F "new_password=new_admin_password"

Error Codes

The API uses standard HTTP status codes and returns detailed error messages.

HTTP Status Codes

Status CodeDescription
200Success
404Endpoint not found
405Method not allowed (use POST)
413Request entity too large (file > 2MB)
415Unsupported media type (use JPEG, JPG, PNG)
420Missing required parameter
421Invalid parameter value
422Invalid parameter format
423Face not detected in image
424Multiple faces detected (use /multi endpoint)
425New password same as old password
426Admin permission required
427Operation not allowed for demo account
428Database export failed
429Import failed

Error Response Format

{
"message": "Error description",
"error_code": 421,
"parameter": "company"
}

Common Errors

420 - Missing Required Parameter

{
"message": "Missing required parameter: company",
"error_code": 420,
"parameter": "company"
}

421 - Invalid Parameter

{
"message": "Invalid value for parameter: password",
"error_code": 421,
"parameter": "password"
}

423 - Face Not Detected

{
"message": "No face detected in the image",
"error_code": 423
}

424 - Multiple Faces Detected

{
"message": "Multiple faces detected. Please use /recog/multi endpoint",
"error_code": 424
}

Code Examples

Python

import requests

def recognize_face(image_path, api_key, company):
"""Recognize face in image"""
url = "https://api.iapp.co.th/v3/store/ekyc/face-recognition/single"

files = {
'file': open(image_path, 'rb')
}
data = {
'company': company
}
headers = {
'apikey': api_key
}

response = requests.post(url, headers=headers, data=data, files=files)
return response.json()

def add_face_to_database(image_path, api_key, company, name, password):
"""Add new face to database"""
url = "https://api.iapp.co.th/v3/store/ekyc/face-recognition/add"

files = {
'file': open(image_path, 'rb')
}
data = {
'company': company,
'name': name,
'password': password
}
headers = {
'apikey': api_key
}

response = requests.post(url, headers=headers, data=data, files=files)
return response.json()

def compare_faces(image1_path, image2_path, api_key):
"""Compare two faces"""
url = "https://api.iapp.co.th/v3/store/ekyc/face-comparison"

files = {
'file1': open(image1_path, 'rb'),
'file2': open(image2_path, 'rb')
}
headers = {
'apikey': api_key
}

response = requests.post(url, headers=headers, files=files)
return response.json()

# Usage examples
if __name__ == "__main__":
API_KEY = "your_api_key"
COMPANY = "your_company"

# Recognize face
result = recognize_face("photo.jpg", API_KEY, COMPANY)
print(f"Recognized: {result['name']}")
print(f"Confidence: {result['recognition_score']:.2%}")

# Add face to database
result = add_face_to_database(
"john_doe.jpg",
API_KEY,
COMPANY,
"John Doe",
"your_password"
)
print(f"Added: {result['name']}")

# Compare two faces
result = compare_faces("face1.jpg", "face2.jpg", API_KEY)
print(f"Match: {result['status']['match']}")
print(f"Similarity: {result['similarity_score']:.2%}")

JavaScript (Node.js)

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

async function recognizeFace(imagePath, apiKey, company) {
const formData = new FormData();
formData.append('file', fs.createReadStream(imagePath));
formData.append('company', company);

try {
const response = await axios.post(
'https://api.iapp.co.th/v3/store/ekyc/face-recognition/single',
formData,
{
headers: {
'apikey': apiKey,
...formData.getHeaders()
}
}
);
return response.data;
} catch (error) {
console.error('Error:', error.response?.data || error.message);
throw error;
}
}

async function addFaceToDatabase(imagePath, apiKey, company, name, password) {
const formData = new FormData();
formData.append('file', fs.createReadStream(imagePath));
formData.append('company', company);
formData.append('name', name);
formData.append('password', password);

try {
const response = await axios.post(
'https://api.iapp.co.th/v3/store/ekyc/face-recognition/add',
formData,
{
headers: {
'apikey': apiKey,
...formData.getHeaders()
}
}
);
return response.data;
} catch (error) {
console.error('Error:', error.response?.data || error.message);
throw error;
}
}

async function compareFaces(image1Path, image2Path, apiKey) {
const formData = new FormData();
formData.append('file1', fs.createReadStream(image1Path));
formData.append('file2', fs.createReadStream(image2Path));

try {
const response = await axios.post(
'https://api.iapp.co.th/v3/store/ekyc/face-comparison',
formData,
{
headers: {
'apikey': apiKey,
...formData.getHeaders()
}
}
);
return response.data;
} catch (error) {
console.error('Error:', error.response?.data || error.message);
throw error;
}
}

// Usage examples
(async () => {
const API_KEY = 'your_api_key';
const COMPANY = 'your_company';

try {
// Recognize face
const result = await recognizeFace('photo.jpg', API_KEY, COMPANY);
console.log('Recognized:', result.name);
console.log('Confidence:', result.recognition_score);

// Add face to database
const addResult = await addFaceToDatabase(
'john_doe.jpg',
API_KEY,
COMPANY,
'John Doe',
'your_password'
);
console.log('Added:', addResult.name);

// Compare two faces
const compareResult = await compareFaces('face1.jpg', 'face2.jpg', API_KEY);
console.log('Match:', compareResult.status.match);
console.log('Similarity:', compareResult.similarity_score);
} catch (error) {
console.error('Error:', error);
}
})();

JavaScript (Browser)

// Face Recognition Function
async function recognizeFace(fileInput, apiKey, company) {
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('company', company);

try {
const response = await fetch('https://api.iapp.co.th/v3/store/ekyc/face-recognition/single', {
method: 'POST',
headers: {
'apikey': apiKey
},
body: formData
});

const data = await response.json();
return data;
} catch (error) {
console.error('Error:', error);
throw error;
}
}

// Add Face to Database
async function addFaceToDatabase(fileInput, apiKey, company, name, password) {
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('company', company);
formData.append('name', name);
formData.append('password', password);

try {
const response = await fetch('https://api.iapp.co.th/v3/store/ekyc/face-recognition/add', {
method: 'POST',
headers: {
'apikey': apiKey
},
body: formData
});

const data = await response.json();
return data;
} catch (error) {
console.error('Error:', error);
throw error;
}
}

// Compare Two Faces
async function compareFaces(fileInput1, fileInput2, apiKey) {
const formData = new FormData();
formData.append('file1', fileInput1.files[0]);
formData.append('file2', fileInput2.files[0]);

try {
const response = await fetch('https://api.iapp.co.th/v3/store/ekyc/face-comparison', {
method: 'POST',
headers: {
'apikey': apiKey
},
body: formData
});

const data = await response.json();
return data;
} catch (error) {
console.error('Error:', error);
throw error;
}
}

// HTML Example
/*
<input type="file" id="faceImage" accept="image/*">
<input type="text" id="company" placeholder="Company">
<button onclick="handleRecognize()">Recognize Face</button>

<script>
async function handleRecognize() {
const fileInput = document.getElementById('faceImage');
const company = document.getElementById('company').value;
const apiKey = 'your_api_key';

const result = await recognizeFace(fileInput, apiKey, company);
console.log('Result:', result);
alert(`Recognized: ${result.name}\nConfidence: ${result.recognition_score}`);
}
</script>
*/

PHP

<?php

class FaceRecognitionAPI {
private $apiKey;
private $baseUrl = 'https://api.iapp.co.th';

public function __construct($apiKey) {
$this->apiKey = $apiKey;
}

public function recognizeFace($imagePath, $company) {
$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => $this->baseUrl . '/v3/store/ekyc/face-recognition/single',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => array(
'file' => new CURLFile($imagePath),
'company' => $company
),
CURLOPT_HTTPHEADER => array(
'apikey: ' . $this->apiKey
),
));

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($httpCode !== 200) {
throw new Exception("API request failed with code: $httpCode");
}

return json_decode($response, true);
}

public function addFaceToDatabase($imagePath, $company, $name, $password) {
$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => $this->baseUrl . '/v3/store/ekyc/face-recognition/add',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => array(
'file' => new CURLFile($imagePath),
'company' => $company,
'name' => $name,
'password' => $password
),
CURLOPT_HTTPHEADER => array(
'apikey: ' . $this->apiKey
),
));

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($httpCode !== 200) {
throw new Exception("API request failed with code: $httpCode");
}

return json_decode($response, true);
}

public function compareFaces($image1Path, $image2Path) {
$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => $this->baseUrl . '/v3/store/ekyc/face-comparison',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => array(
'file1' => new CURLFile($image1Path),
'file2' => new CURLFile($image2Path)
),
CURLOPT_HTTPHEADER => array(
'apikey: ' . $this->apiKey
),
));

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($httpCode !== 200) {
throw new Exception("API request failed with code: $httpCode");
}

return json_decode($response, true);
}

public function detectFaces($imagePath, $multiplefaces = false) {
$endpoint = $multiplefaces ? '/v3/store/ekyc/face-detection/multi' : '/v3/store/ekyc/face-detection/single';
$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => $this->baseUrl . $endpoint,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => array(
'file' => new CURLFile($imagePath)
),
CURLOPT_HTTPHEADER => array(
'apikey: ' . $this->apiKey
),
));

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($httpCode !== 200) {
throw new Exception("API request failed with code: $httpCode");
}

return json_decode($response, true);
}
}

// Usage example
$api = new FaceRecognitionAPI('your_api_key');

try {
// Recognize face
$result = $api->recognizeFace('photo.jpg', 'your_company');
echo "Recognized: " . $result['name'] . "\n";
echo "Confidence: " . ($result['recognition_score'] * 100) . "%\n";

// Add face to database
$result = $api->addFaceToDatabase('john_doe.jpg', 'your_company', 'John Doe', 'your_password');
echo "Added: " . $result['name'] . "\n";

// Compare two faces
$result = $api->compareFaces('face1.jpg', 'face2.jpg');
echo "Match: " . ($result['status']['match'] ? 'Yes' : 'No') . "\n";
echo "Similarity: " . ($result['similarity_score'] * 100) . "%\n";

// Detect faces
$result = $api->detectFaces('group_photo.jpg', true);
echo "Total faces detected: " . $result['total_faces'] . "\n";

} catch (Exception $e) {
echo "Error: " . $e->getMessage() . "\n";
}
?>

cURL Examples

# Single Face Recognition
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/single \
-H "apikey: YOUR_API_KEY" \
-F "file=@photo.jpg" \
-F "company=YOUR_COMPANY"

# Multi-Face Recognition
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/multi \
-H "apikey: YOUR_API_KEY" \
-F "file=@group_photo.jpg" \
-F "company=YOUR_COMPANY"

# Add Face to Database
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/add \
-H "apikey: YOUR_API_KEY" \
-F "file=@john_doe.jpg" \
-F "company=iApp" \
-F "name=John Doe" \
-F "password=iApp"

# Remove Face from Database
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/remove \
-H "apikey: YOUR_API_KEY" \
-F "company=iApp" \
-F "name=John Doe" \
-F "password=iApp"

# Compare Two Faces
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-comparison \
-H "apikey: YOUR_API_KEY" \
-F "file1=@face1.jpg" \
-F "file2=@face2.jpg" \
-F "min_score=0.8"

# Detect Single Face
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-detection/single \
-H "apikey: YOUR_API_KEY" \
-F "file=@photo.jpg"

# Detect Multiple Faces
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-detection/multi \
-H "apikey: YOUR_API_KEY" \
-F "file=@group_photo.jpg"

# Configure Thresholds
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/config \
-H "apikey: YOUR_API_KEY" \
-F "company=iApp" \
-F "password=iApp" \
-F "detection=75" \
-F "recognition=85"

# Check Database
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/check \
-H "apikey: YOUR_API_KEY" \
-F "company=iApp" \
-F "password=iApp"

# Export Database (CSV)
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/export \
-H "apikey: YOUR_API_KEY" \
-F "company=iApp" \
-F "password=iApp" \
-F "type_file=csv" \
-o face_database.csv

# Export Database (Excel)
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/export \
-H "apikey: YOUR_API_KEY" \
-F "company=iApp" \
-F "password=iApp" \
-F "type_file=excel" \
-o face_database.xlsx

Best Practices

Image Quality Guidelines

For optimal face recognition accuracy:

  1. Image Resolution

    • Minimum: 600x400 pixels
    • Recommended: 1024x768 pixels or higher
    • Face should occupy at least 15-20% of image area
  2. Lighting Conditions

    • Use well-lit, evenly illuminated faces
    • Avoid harsh shadows or backlighting
    • Natural or neutral white light works best
    • Avoid extreme lighting conditions
  3. Face Position

    • Frontal view preferred (±15 degrees)
    • Both eyes should be visible
    • Face should be upright
    • Avoid extreme angles or tilts
  4. Image Quality

    • Use clear, sharp images
    • Avoid motion blur
    • Minimize compression artifacts
    • No filters or heavy editing
  5. Face Coverage

    • Avoid sunglasses, masks, or obstructions
    • Hair should not cover eyes
    • Minimal accessories on face
    • Clear view of facial features

Database Management

  1. Adding Faces

    • Use multiple photos per person (3-5 recommended) for better accuracy
    • Include photos with slight variations (different expressions, lighting)
    • Ensure high-quality images for registration
    • Use descriptive, unique names
  2. Regular Maintenance

    • Periodically review and clean database
    • Remove outdated or duplicate entries
    • Back up database regularly using export feature
    • Monitor database size and performance
  3. Security

    • Use strong passwords
    • Change passwords regularly
    • Limit access to sensitive operations
    • Keep API keys secure

Performance Optimization

  1. Image Preprocessing

    • Resize large images before upload
    • Compress images without losing quality
    • Crop to focus on face area
    • Convert to RGB format
  2. Batch Operations

    • Use import/export for bulk operations
    • Implement retry logic for failed requests
    • Handle timeouts appropriately
    • Monitor API rate limits
  3. Error Handling

    • Implement proper error handling
    • Log errors for debugging
    • Provide user feedback for failures
    • Retry transient errors

Threshold Configuration

  1. Detection Threshold

    • Start with default (0.75)
    • Increase if too many false positives
    • Decrease if missing valid faces
    • Test with your typical image quality
  2. Recognition Threshold

    • Start with default (0.85)
    • Increase for higher security (stricter matching)
    • Decrease for more lenient matching
    • Balance between false accepts and false rejects
  3. Comparison Threshold

    • Use higher threshold (0.80-0.90) for verification
    • Use lower threshold (0.70-0.80) for identification
    • Test with known match/non-match pairs
    • Adjust based on use case requirements

Use Cases

1. Access Control Systems

Use face recognition for physical or digital access control:

  • Employee time and attendance tracking
  • Building access management
  • Secure area authentication
  • Visitor management systems

Implementation:

  1. Register employee faces using /recog/add
  2. Use /recog/single for real-time recognition at entry points
  3. Configure high recognition threshold (0.90+) for security
  4. Log access events with timestamps

2. Identity Verification

Verify user identity for KYC (Know Your Customer) processes:

  • Financial services onboarding
  • Government service authentication
  • Age verification
  • Document verification (compare ID photo with selfie)

Implementation:

  1. Extract face from ID document
  2. Capture live selfie
  3. Use /compare endpoint to match faces
  4. Set comparison threshold based on risk tolerance
  5. Store verification results for audit

3. Photo Organization

Automatically organize and tag photos based on faces:

  • Personal photo library management
  • Event photo categorization
  • Family photo albums
  • Social media applications

Implementation:

  1. Use /detect/multi to find all faces in photos
  2. Use /recog/multi to identify known people
  3. Group photos by detected individuals
  4. Tag unknown faces for manual identification

4. Security and Surveillance

Monitor and identify individuals in security footage:

  • Retail loss prevention
  • Public safety monitoring
  • VIP identification
  • Blacklist screening

Implementation:

  1. Extract frames from video feed
  2. Use /detect/multi to find faces
  3. Use /recog/multi to identify persons of interest
  4. Alert on matches with high confidence
  5. Store detection logs for review

5. Customer Experience

Enhance customer service with face recognition:

  • VIP customer identification
  • Personalized shopping experiences
  • Loyalty program integration
  • Return customer recognition

Implementation:

  1. Register customer faces with consent
  2. Use /recog/single for identification at entry
  3. Retrieve customer preferences and history
  4. Provide personalized service
  5. Respect privacy and data protection regulations

Limitations and Considerations

Technical Limitations

  1. Image Size

    • Maximum file size: 2MB
    • Files exceeding limit will return HTTP 413 error
  2. Face Size

    • Minimum face size: 112x112 pixels
    • Faces smaller than minimum may not be detected
  3. Face Angle

    • Optimal: Frontal view (±15 degrees)
    • Accuracy decreases with extreme angles
  4. Image Quality

    • Low-quality images may result in detection failures
    • Motion blur reduces recognition accuracy
  5. Database Size

    • Large databases may affect recognition speed
    • Regular maintenance recommended

Performance Considerations

  1. Processing Time

    • Typical: 0.3-1.0 seconds per request
    • May increase with server load
    • Multi-face detection takes longer than single face
  2. Accuracy Factors

    • Image quality
    • Lighting conditions
    • Face angle and expression
    • Age progression
    • Facial accessories
  3. Rate Limits

    • API rate limits apply
    • Queue system manages high traffic
    • Contact support for higher limits

Privacy and Compliance

  1. Data Protection

    • No images stored after processing
    • Face features encrypted in database
    • GDPR and PDPA compliant
    • Obtain user consent for face collection
  2. Ethical Use

    • Use for legitimate purposes only
    • Respect privacy rights
    • Implement opt-out mechanisms
    • Transparent about face recognition use
  3. Security

    • Protect API keys
    • Use HTTPS for all requests
    • Secure face database access
    • Regular security audits

Regulatory Compliance

  1. GDPR (Europe)

    • Biometric data is special category data
    • Requires explicit consent
    • Right to erasure applies
    • Data protection impact assessment required
  2. PDPA (Thailand)

    • Biometric data requires consent
    • Notify data subjects of purpose
    • Implement security measures
    • Allow data subject rights
  3. Other Regulations

    • Check local laws and regulations
    • Obtain necessary licenses
    • Implement required safeguards
    • Document compliance measures

Accuracy & Performance

Recognition Accuracy

  • Frontal Faces: 98-99% accuracy
  • Angled Faces (±15°): 95-97% accuracy
  • Angled Faces (±30°): 85-90% accuracy
  • Profile Views: Limited accuracy (not recommended)

Processing Speed

  • Single Face Detection: 0.2-0.3 seconds
  • Single Face Recognition: 0.4-0.6 seconds
  • Multi-Face Detection: 0.3-0.5 seconds
  • Multi-Face Recognition: 0.5-1.0 seconds
  • Face Comparison: 0.4-0.6 seconds

Note: Times are typical values and may vary based on image size, server load, and network latency.

Factors Affecting Performance

  1. Image Quality

    • Higher resolution = Better accuracy, longer processing
    • Compression artifacts reduce accuracy
    • Proper lighting critical for accuracy
  2. Face Database Size

    • Larger database = Slightly longer recognition time
    • Up to 10,000 faces: Minimal impact
    • Over 10,000 faces: Consider database optimization
  3. Network Conditions

    • File upload time affects total response time
    • Use appropriate timeouts
    • Implement retry logic for network failures
  4. Server Load

    • Peak hours may have longer queue times
    • Queue system ensures fair processing
    • Contact support for dedicated resources

Pricing

API Endpoints Pricing

OperationEndpointIC CostUnit
Single Face Recognition/v3/store/ekyc/face-recognition/single0.3 ICper request
Multi-Face Recognition/v3/store/ekyc/face-recognition/multi0.3 ICper request
Add Face to Database/v3/store/ekyc/face-recognition/add0.1 ICper request
Check Database/v3/store/ekyc/face-recognition/check0.3 ICper request
Single Face Detection/v3/store/ekyc/face-detection/single0.3 ICper request
Multi-Face Detection/v3/store/ekyc/face-detection/multi0.3 ICper request
Compare Faces/v3/store/ekyc/face-comparison0.3 ICper request
Remove Face/v3/store/ekyc/face-recognition/remove0 ICper request
Import Features/v3/store/ekyc/face-recognition/import0 ICper request
Export Features/v3/store/ekyc/face-recognition/export0 ICper request
Configure Thresholds/v3/store/ekyc/face-recognition/config0 ICper request
Change Password/v3/store/ekyc/face-recognition/password/change0 ICper request

On-Premise Deployment

For high-volume usage or sensitive data requirements, consider on-premise deployment:

  • Unlimited API calls
  • No data leaves your infrastructure
  • Custom integration support
  • Dedicated technical support
  • Custom threshold configuration
  • Custom database management

Contact us for on-premise licensing and pricing.


Support

Documentation

  • API Reference: Complete endpoint documentation (this page)
  • Integration Guides: Language-specific integration guides
  • Code Examples: Ready-to-use code samples
  • Best Practices: Optimization and security guidelines

Technical Support

Business Inquiries

For enterprise solutions, custom integration, or on-premise deployment:


Changelog

Version 1.3.0 (Current)

  • Enhanced multi-face recognition accuracy
  • Improved detection for angled faces
  • Added admin endpoints for database management
  • Optimized processing speed
  • Enhanced error handling and reporting
  • Added comprehensive API documentation

Version 1.2.0

  • Added face comparison endpoint
  • Improved recognition threshold configuration
  • Enhanced database import/export functionality
  • Added password management features
  • Performance optimizations

Version 1.1.0

  • Added multi-face detection and recognition
  • Introduced configurable score thresholds
  • Enhanced error messages
  • Added database management features
  • Performance improvements

Version 1.0.0

  • Initial release
  • Single face recognition
  • Face detection
  • Basic database management


© 2025 iApp Technology Co., Ltd. All rights reserved.

This API is continuously improved based on user feedback and technological advancements. Please check for updates regularly.