Selfie Liveness & Face Match

e-verify integrates with Amazon Rekognition to provide robust selfie liveness detection and face matching capabilities. This service helps verify the authenticity of a user during remote onboarding processes, preventing spoofing attacks and ensuring the person presenting the ID is the legitimate owner.

Endpoints

Start Liveness Session

POST /v1/biometrics/liveness/start

Initiates a liveness detection session. The response will include a session ID and instructions for the client-side SDK to capture the liveness video.

Request Body

Field	Type	Description	Required
client_session_token	string	A unique token generated by your client-side application to identify the session.	Yes

Example Request

POST /v1/biometrics/liveness/start HTTP/1.1
Host: api.e-verify.co.za
X-API-Key: ev_live_YOUR_API_KEY
Content-Type: application/json

{
  "client_session_token": "your_unique_client_session_token"
}

Response

{
  "request_id": "req_liveness_start_123",
  "session_id": "liveness_session_abc",
  "challenge_details": {
    "challenge_type": "blink",
    "instructions": "Please blink your eyes"
  },
  "message": "Liveness session started successfully."
}

Get Liveness Results

GET /v1/biometrics/liveness/{session_id}/results

Retrieves the results of a completed liveness detection session.

Path Parameters

Parameter	Type	Description
session_id	string	The ID of the liveness session obtained from the start endpoint.

Example Request

GET /v1/biometrics/liveness/liveness_session_abc/results HTTP/1.1
Host: api.e-verify.co.za
X-API-Key: ev_live_YOUR_API_KEY

Response

{
  "request_id": "req_liveness_results_123",
  "session_id": "liveness_session_abc",
  "status": "completed",
  "result": {
    "liveness_score": 98.5,
    "is_live": true,
    "spoof_attempt_detected": false
  },
  "message": "Liveness detection results retrieved successfully."
}

Face Match

POST /v1/biometrics/face-match

Compares a face from a live capture (or provided image) against a face from an identity document.

Request Body

Field	Type	Description	Required
source_image_url	string	URL of the image containing the face to be compared (e.g., from a selfie).	Yes
target_image_url	string	URL of the image containing the face from the identity document.	Yes
threshold	number	(Optional) Confidence threshold for face matching (0-100). Default is 80.	No

Example Request

POST /v1/biometrics/face-match HTTP/1.1
Host: api.e-verify.co.za
X-API-Key: ev_live_YOUR_API_KEY
Content-Type: application/json

{
  "source_image_url": "https://example.com/selfie.jpg",
  "target_image_url": "https://example.com/id_photo.jpg",
  "threshold": 85
}

Response

{
  "request_id": "req_face_match_123",
  "status": "completed",
  "result": {
    "match_score": 92.1,
    "is_match": true,
    "confidence": 95.0
  },
  "message": "Face matching completed successfully."
}

Error Codes

Code	Description
400	Invalid input data
401	Unauthorized
403	Forbidden
500	Internal server error