Face Liveness V3

Endpoint Overview

POST /api/v1/face/face-liveness-v3

Description

The Face Liveness V3 API provides advanced biometric verification to detect whether a face in an image is real (live) or fake (spoofed). This API analyzes facial characteristics and image properties to identify presentation attacks such as photos, videos, masks, or deepfakes. The service returns a comprehensive assessment including a binary classification (real/spoof) along with confidence scores and image attributes to help you make informed authentication decisions.

Key Benefits

Enhanced Security: Protect against sophisticated presentation attacks and identity fraud

Seamless Integration: Simple API design with multiple input options (file upload, base64, or URL)

Detailed Analysis: Provides confidence scores and facial positioning metrics for better decision-making

Fraud Prevention: Reduces the risk of unauthorized access in digital onboarding and authentication flows

Use Cases

Financial Services

Identity Verification

Access Control

Secure customer onboarding during digital account opening

Protect high-value transactions with additional biometric verification

Enhance security for mobile banking authentication

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.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

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

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token authentication using JWT
Content-Type	Yes	`multipart/form-data` for file uploads or `application/json` for base64/URL inputs

Request Body

The API supports three different input methods. Choose one based on your implementation needs:

Option 1: File Upload

Parameter	Type	Required	Description
file	File	Yes	The image file containing the face to be analyzed
use_pdf	Boolean	No	Set to `true` if the uploaded file is a PDF (default: `false`)

Option 2: Base64 Encoded Image

Parameter	Type	Required	Description
base_64	String	Yes	Base64 encoded string of the image containing the face

Option 3: Image URL

Parameter	Type	Required	Description
link	String	Yes	Public URL of the image containing the face

Example Request (using URL)

{
  "link": "https://example.com/face-image.jpg"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the response data
data.client_id	String	Unique identifier for the request
data.model_output	Object	Contains the liveness detection results
data.model_output.pred_idx	String	Classification result: `real` (live face) or `spoof` (presentation attack)
data.model_output.prob_real	String	Probability score (0-1) indicating likelihood of the face being real
data.image_attributes	Object	Contains image and facial positioning metrics
data.image_attributes.yaw	String	Side angle the face makes with respect to the center vertical axis
data.image_attributes.bbox_to_img_ratio	String	Ratio of face bounding box area to total image area
status_code	Integer	HTTP status code
success	Boolean	Indicates if the API call was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "client_id": "face_liveness_v3_gWUdURAoyqtVyFqDqxiE",
        "model_output": {
            "pred_idx": "spoof",
            "prob_real": "0.016860956326127052"
        },
        "image_attributes": {
            "yaw": "-1000",
            "bbox_to_img_ratio": "0.0322921875"
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Invalid Input

Processing Error

{
    "detail": "Authentication credentials were not provided or are invalid",
    "status_code": 401,
    "success": false
}

This error occurs when the JWT token is missing, expired, or invalid.

Integration Best Practices

Security Recommendations

Store API credentials securely and never expose them in client-side code

Implement proper error handling to prevent information leakage

Use HTTPS for all API communications

Implement rate limiting on your end to prevent abuse

Rotate JWT tokens periodically for enhanced security

User Experience Guidelines

Provide clear instructions to users for optimal face capture

Ensure adequate lighting and recommend a neutral background

Implement a user-friendly retry mechanism for failed verifications

Display appropriate feedback during processing to maintain user engagement

Consider implementing progressive enhancement for different device capabilities

Code Samples

cURL

Python

Node.js

Related APIs

Face Match API: Compare two face images to determine if they belong to the same person

Face Detection API: Detect and extract facial features from images

Document Verification API: Verify identity documents with face matching capabilities

OCR API: Extract text information from identity documents

Compliance and Legal Considerations

When implementing face liveness detection, ensure compliance with applicable privacy regulations such as GDPR, CCPA, or other regional data protection laws. Always obtain proper user consent before capturing and processing biometric data, and clearly communicate how the data will be used. Implement appropriate data retention policies and security measures to protect sensitive biometric information.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "client_id": "face_liveness_v3_gWUdURAoyqtVyFqDqxiE", "model_output": { "pred_idx": "spoof", "prob_real": "0.016860956326127052" }, "image_attributes": { "yaw": "-1000", "bbox_to_img_ratio": "0.0322921875" } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Face Liveness V3

Face Liveness V3#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Option 1: File Upload#

Option 2: Base64 Encoded Image#

Option 3: Image URL#

Example Request (using URL)#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Face Liveness V3

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Option 1: File Upload

Option 2: Base64 Encoded Image

Option 3: Image URL

Example Request (using URL)

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples