Face Recognition

Names the people in a photograph from a face database you keep with us: register a face under a name, then recognise it in later images, one face or every face at once.

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

+7 endpoints

Try it

• Price0.3 ICper request
• Served44.1Kcalls

• v1.3.0
• Active

Input

file

photo.jpg

company

iApp

OutputPOST /v3/store/ekyc/face-recognition/single

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

Every field, under ResponseOther endpoints: /add, /check, /export, /facecrop, /import, /multi, /remove see Request

Request

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"

Response

200OK. The fields are explained under Response.

{
  "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
}

Request

multipart/form-data. Every call names the database in company, and calls that change it also take its password; the demo database is iApp, password iApp.

Headers

apikeystringrequired

Your API key, created under API Keys in the control panel.

Body

filefilerequired

The photograph. JPEG or PNG, up to 2 MB, at least 600 × 400 px; a face at least 112 × 112 px.

companystringrequired

Your company identifier, which names your face database.

Endpoint	Does	Price
/v3/store/ekyc/face-recognition/single	Recognises the most prominent face	0.3 IC per request
/v3/store/ekyc/face-recognition/multi	Recognises every face, as faces[]	0.3 IC per request
/v3/store/ekyc/face-recognition/add	Registers a face under name	0.1 IC per request
/v3/store/ekyc/face-recognition/remove	Removes a name, or one face_id	Free
/v3/store/ekyc/face-recognition/check	Counts the database; save_file=1 returns it as CSV	0.3 IC per request
/v3/store/ekyc/face-recognition/import, /export	Moves face features in and out as CSV or Excel (type_file)	Free

The database calls

Endpoint	Fields	Returns
/add	file, company, name, password	face_id, detection_score
/remove	company, name, password, and face_id to remove one of several	removed_count
/check	company, password, save_file	total_faces, total_persons, database_size, last_updated
/import	file (CSV with name, face_id, feature_vector), company, password	imported_count, failed_count
/export	company, password, type_file = csv or excel	The file

Register 3 to 5 sharp, frontal, well-lit photographs per person, with some variation in expression. The service matches with thresholds of detection 0.75, comparison 0.80 and recognition 0.85. The demo database does not allow import or export.

Response

/single returns the best match at the top level, as in the panel; /multi returns the same fields for each face inside faces.

namestring

The registered name, or unknown when no face in the database reaches the recognition threshold

recognition_scorenumber

Confidence in the name, 0 to 1

detection_scorebbox

Confidence in the face and its xmin, ymin, xmax, ymax

messagecompanyprocess_time

successfully performed; the database; seconds

Status codes

Code	Meaning
413	The file is over 2 MB
415	Unsupported file format
420, 421, 422	A required field is missing, invalid, or malformed; parameter names it
423	No face found in the image
424	Several faces found; use /multi
427	Not allowed on the demo database
428, 429	Export or import failed

Details

Measured

Measure	Result
Frontal faces	98 to 99%
Faces turned up to 15°	95 to 97%
Faces turned up to 30°	85 to 90%
Time, detection	0.2 to 0.3 s
Time, recognition of one face	0.4 to 0.6 s

Limits

• Best when the face fills 15% or more of the frame.
• Frontal within 15°, both eyes visible, no sunglasses or mask; profile views are not recommended.
• Lighting, sharpness, expression, age and accessories lower the score.
• A large database recognises more slowly; export a backup and remove stale entries.

Data handling

Images are not kept after processing; only the face features are stored, encrypted, in your database. Biometric data needs the subject's explicit consent under GDPR and PDPA, and the right to erasure applies: /remove deletes a person on request.