👤🔍 Face Recognition API
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!
Try Our AI Demo
Login or create a free account to use this AI service demo and explore our powerful APIs.
Get 100 Free Credits (IC) when you sign up!
Offer ends December 31, 2025
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.
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"
Please visit API Key Management page to view your existing API key or request a new one.
API Endpoints
Recognition Endpoints
| Endpoint | Method | Description | Cost |
|---|---|---|---|
| /v3/store/ekyc/face-recognition/single | POST | Recognize the most prominent face | 0.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
| Endpoint | Method | Description | Cost |
|---|---|---|---|
| /v3/store/ekyc/face-detection/single | POST | Detect single face with bounding box | 0.3 IC |
| /v3/store/ekyc/face-detection/multi | POST | Detect all faces in image | 0.3 IC |
Comparison Endpoint
| Endpoint | Method | Description | Cost |
|---|---|---|---|
| /v3/store/ekyc/face-comparison | POST | Compare two faces for similarity | 0.3 IC |
Configuration Endpoints
| Endpoint | Method | Description | Cost |
|---|---|---|---|
| /v3/store/ekyc/face-recognition/config | POST | Configure detection/recognition thresholds | 0 IC |
| /v3/store/ekyc/face-recognition/password/change | POST | Change company password | 0 IC |
Admin Endpoints
| Endpoint | Method | Description | Cost |
|---|---|---|---|
| /v3/store/ekyc/face-recognition/admin/import | POST | Admin: Import features | 0 IC |
| /v3/store/ekyc/face-recognition/admin/export | POST | Admin: Export features | 0 IC |
| /v3/store/ekyc/face-recognition/admin/config | POST | Admin: Configure thresholds | 0 IC |
| /v3/store/ekyc/face-recognition/admin/check | POST | Admin: Check database | 0 IC |
| /v3/store/ekyc/face-recognition/admin/password/change | POST | Admin: Change password | 0 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
file | File | Yes | Image file (JPEG, JPG, PNG, max 2MB) |
company | String | Yes | Your 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 coordinatesprocess_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:
| Parameter | Type | Required | Description |
|---|---|---|---|
file | File | Yes | Image file (JPEG, JPG, PNG, max 2MB) |
company | String | Yes | Your 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
file | File | Yes | Clear face image (JPEG, JPG, PNG, max 2MB) |
company | String | Yes | Your company identifier |
name | String | Yes | Person's name for identification |
password | String | Yes | Company 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 facedetection_score: Quality score of the face imagename: 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"
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
company | String | Yes | Your company identifier |
name | String | Yes | Person's name to remove |
password | String | Yes | Company password for authentication |
face_id | String | No | Specific 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
company | String | Yes | Your company identifier |
password | String | Yes | Company password for authentication |
save_file | String | No | Set 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
file | File | Yes | CSV file containing face features |
company | String | Yes | Your company identifier |
password | String | Yes | Company 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
company | String | Yes | Your company identifier |
password | String | Yes | Company password for authentication |
type_file | String | Yes | Export 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
file | File | Yes | Image file (JPEG, JPG, PNG, max 2MB) |
company | String | No | Optional 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
file | File | Yes | Image file (JPEG, JPG, PNG, max 2MB) |
company | String | No | Optional 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
file1 | File | Yes | First face image (JPEG, JPG, PNG, max 2MB) |
file2 | File | Yes | Second face image (JPEG, JPG, PNG, max 2MB) |
company | String | No | Optional company identifier |
min_score | Float | No | Minimum 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 facesface1_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:
| Parameter | Type | Required | Description |
|---|---|---|---|
company | String | Yes | Your company identifier |
password | String | Yes | Company password for authentication |
detection | Float | No | Detection threshold (0-100 or 0-1) |
comparison | Float | No | Comparison threshold (0-100 or 0-1) |
recognition | Float | No | Recognition 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
company | String | Yes | Your company identifier |
old_password | String | Yes | Current password |
new_password | String | Yes | New 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
company | String | Yes | Must be "admin" |
password | String | Yes | Admin password |
file | File | Yes | CSV 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
company | String | Yes | Must be "admin" |
password | String | Yes | Admin password |
type_file | String | Yes | Export 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
company | String | Yes | "admin" or "demo" |
password | String | Yes | Admin password |
detection | Float | No | Detection threshold (0-100 or 0-1) |
comparison | Float | No | Comparison threshold (0-100 or 0-1) |
recognition | Float | No | Recognition 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
company | String | Yes | "admin" or "demo" |
password | String | Yes | Admin password |
save_file | String | No | Set 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
company | String | Yes | "admin" or "demo" |
old_password | String | Yes | Current admin password |
new_password | String | Yes | New 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 Code | Description |
|---|---|
200 | Success |
404 | Endpoint not found |
405 | Method not allowed (use POST) |
413 | Request entity too large (file > 2MB) |
415 | Unsupported media type (use JPEG, JPG, PNG) |
420 | Missing required parameter |
421 | Invalid parameter value |
422 | Invalid parameter format |
423 | Face not detected in image |
424 | Multiple faces detected (use /multi endpoint) |
425 | New password same as old password |
426 | Admin permission required |
427 | Operation not allowed for demo account |
428 | Database export failed |
429 | Import 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
}