Face Liveness Detection V4

Endpoint Overview

POST /api/v1/ocr/face-liveness-v4

Description

The Face Liveness V4 API provides a real-time liveness detection service to confirm whether a face captured in an image is from a physically present human being or a spoof (e.g., photo, video, mask). This helps businesses implement secure facial recognition and onboarding processes using advanced computer vision and biometric analysis.

It evaluates features such as eye movement, facial texture, and liveliness signals using machine learning to prevent fraudulent authentication attempts and identity spoofing.

Key Benefits

Prevents identity fraud through real-time biometric verification

Detects advanced spoofing techniques including masks and videos

Provides high-confidence scoring and detailed feedback

Easy integration into mobile and web applications

Use Cases

Fintech & Banking

Telecom

Gig & Delivery Platforms

Prevent fraudulent account opening during eKYC

Ensure genuine users during online loan applications

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Base URLs:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer JWT token for API access
Content-Type	Yes	multipart/form-data

Request Body

Parameter	Type	Required	Description
file	Image/PDF	Yes	Image file containing the face to be verified
link	String	No	Image Link
use_pdf	Boolean	No	Use PDF instead of Image

Example Request

Process Response

Response Parameters

Parameter	Type	Description
data.client_id	string	Unique identifier for the request
data.liveness	string	Liveness result: `real` or `spoof`
data.confidence	float	Confidence score for the liveness result
data.eye_state	string	Detected eye state: `open`, `closed`, etc.
data.eye_state_confidence	float	Confidence score for eye state detection
status_code	integer	HTTP status code
success	boolean	Indicates request success
message	string	Success or error message
message_code	string	Internal message code

Example Successful Response

{
  "data": {
    "client_id": "face_liveness_v4_hsIjZtfdztuechNfHMfn",
    "liveness": "real",
    "confidence": 0.964,
    "eye_state": "open",
    "eye_state_confidence": 0.9
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

Invalid Token

Invalid Input

{
  "success": false,
  "message": "Invalid or missing authorization token.",
  "status_code": 401,
  "message_code": "unauthorized"
}

Token is missing, expired, or incorrect.

Integration Best Practices

Security Recommendations

Always use HTTPS to encrypt data in transit

Rotate JWT tokens periodically and store them securely

User Experience Guidelines

Use clear instructions for users when capturing live face images

Inform users if liveness check fails and provide retry options

Code Samples

cURL

Python

Node.js

Related APIs

Face Match V4: Compare two face images for identity verification

ID OCR V3: Extract text and fields from identity documents

Liveness+Match API: Perform both spoof detection and identity match in a single call

Compliance and Legal Considerations

Ensure that face data is processed in compliance with local data privacy laws such as GDPR or IT Act (India). User consent must be explicitly collected before capturing biometric data.

{ "data": { "client_id": "face_liveness_v4_hsIjZtfdztuechNfHMfn", "liveness": "real", "confidence": 0.964, "eye_state": "open", "eye_state_confidence": 0.9 }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Face Liveness V4

Face Liveness Detection V4#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Face Liveness Detection V4

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples