Face Liveness

Endpoint Overview

POST /api/v1/face/face-liveness

Description

The Face Liveness API detects whether a facial image is from a live person or a spoofed representation (such as a photo, video, or mask). This endpoint helps prevent identity fraud by ensuring that the person being verified is physically present during the verification process, not using pre-recorded media or other presentation attack methods.

Key Benefits

Prevents identity spoofing attacks by detecting non-live facial presentations

Enhances security for remote onboarding and authentication processes

Provides confidence scores to help make informed verification decisions

Seamlessly integrates with other identity verification workflows

Use Cases

Financial Services

Identity Verification

Access Control

Secure customer onboarding for banking and financial applications

Additional security layer for high-value transactions

Passwordless authentication for mobile banking 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.

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 for authentication. Format: `Bearer YOUR_JWT_TOKEN`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
file	Image/Pdf	Yes	Image of face
link	String	No	Image link url
use_pdf	Boolean	No	Use PDF instead of image

Example Request

file=@"/path/to/file"

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the liveness detection results
data.confidence	Number	Confidence score (0-10) indicating the certainty of the liveness detection
data.live	Boolean	Indicates whether the face is determined to be live (`true`) or not (`false`)
message	String or null	Additional information about the response (null if no message)
success	Boolean	Indicates whether the API call was successful
status_code	Number	HTTP status code of the response
message_code	String	A code representing the status of the request

Example Successful Response

{
    "data": {
        "confidence": 7,
        "live": false
    },
    "message": null,
    "success": true,
    "status_code": 200,
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Invalid Image

{
    "data": null,
    "message": "Invalid or expired token",
    "success": false,
    "status_code": 401,
    "message_code": "unauthorized"
}

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

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement token refresh mechanisms to maintain secure sessions

Use HTTPS for all API communications to ensure data encryption in transit

Implement proper error handling to avoid exposing sensitive information

User Experience Guidelines

Provide clear instructions to users for capturing their facial image

Implement a user-friendly interface with visual feedback during the liveness check

Include appropriate fallback mechanisms if liveness detection fails

Consider implementing progressive enhancement for different device capabilities

Code Samples

cURL

Python

Node.js

Related APIs

Face Match API - Compares two facial images to determine if they belong to the same person

Face Detection API - Detects and extracts facial features from images

ID Verification API - Verifies identity documents and extracts information

Compliance and Legal Considerations

When implementing face liveness detection, be aware of biometric data privacy regulations such as GDPR, CCPA, and BIPA. Ensure proper user consent is obtained before collecting and processing facial biometric data. Maintain transparency about how the data is used, stored, and protected. Consider implementing data minimization practices by not storing raw facial images longer than necessary.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Face Liveness

Face Liveness#

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

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples