Face Liveness Detection V5

Endpoint Overview

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

Description

The Face Liveness Detection V5 API is a cutting-edge biometric verification solution that determines whether a face presented in an image or video frame belongs to a live person or is a spoofing attempt (e.g., a photograph, screen replay, or mask). Powered by advanced deep-learning anti-spoofing models, the API analyzes facial regions, computes liveness and anti-spoof scores, and returns a clear verdict with granular confidence metrics.

This API is purpose-built for KYC (Know Your Customer) pipelines, onboarding workflows, and access control systems where confirming physical presence is critical to preventing fraud. It accepts image files or publicly accessible URLs and returns structured JSON data including bounding box coordinates, detection scores, and a human-readable verdict.

Key Benefits

Fraud Prevention: Detects presentation attacks such as printed photos, digital screens, and 3D masks with high accuracy using anti-spoof scoring.

High Precision Scoring: Returns individual liveness_score and antispoof_score per face, plus a configurable threshold for fine-tuned decisioning.

Multi-Face Support: Processes multiple faces within a single frame, returning bounding box and scores for each detected face.

Flexible Input: Supports both direct file uploads (images and PDFs) and remote URL-based inputs for seamless integration with existing media pipelines.

Use Cases

Banking & Finance

Healthcare

Government & Compliance

Remote Account Opening: Verify that the applicant is physically present during digital KYC onboarding to prevent identity fraud.

Transaction Authorization: Re-authenticate users with liveness checks before approving high-value transactions.

Loan & Credit Applications: Ensure face presented during e-sign or document submission is live, not a spoofed image.

Technical Implementation

Authentication

All API requests must be authenticated using a JWT Bearer Token. Follow these steps to authenticate:

Obtain API Credentials: Register on the Surepass platform to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token through the Surepass token issuance process.

Include in Requests: Attach the token to every request via the Authorization HTTP header in the format:

Authorization: Bearer <YOUR_JWT_TOKEN>

Use environment-specific base URLs with their corresponding JWT tokens:

Environment	Base URL
Sandbox	`https://sandbox.surepass.app`
Production	`https://kyc-api.surepass.app`

⚠️ Important: Sandbox and production environments use separate authentication tokens. Never use a production token against the sandbox endpoint or vice versa.

Request Parameters

Request Headers

Header	Required	Description
`Authorization`	Yes	JWT Bearer token in the format `Bearer <token>`
`Content-Type`	Yes	Must be `multipart/form-data` when uploading a file

Request Body

The request body is sent as multipart/form-data. At least one of file or link is mandatory.

Parameter	Type	Required	Description
`file`	File (binary)	Conditional	The image or PDF file to be analyzed. Must be sent as `application/octet-stream`. Required if `link` is not provided.
`link`	String (URL)	Conditional	A publicly accessible URL pointing to the image to be analyzed. Required if `file` is not provided.
`use_pdf`	Boolean	Conditional	Set to `true` when the input `file` is a PDF document. Only applicable for file uploads.

Example Request (File Upload)

Example Request (URL Input)

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

Example Request (PDF File Upload)

Process Response

Response Parameters

Top-Level Fields

Parameter	Type	Description
`status_code`	Integer	HTTP status code of the response (e.g., `200` for success).
`success`	Boolean	`true` if the request was processed successfully, `false` otherwise.
`message`	String	Human-readable status message (e.g., `"Success"`).
`message_code`	String	Machine-readable status code (e.g., `"success"`).
`data`	Object	Container object holding the liveness analysis result.
`data.client_id`	String	A unique identifier assigned to this specific API request.
`data.detail`	Object	The core analysis result object containing all liveness verdicts and face data.

`data.detail` Fields

Parameter	Type	Description
`ok`	Boolean	`true` if the API successfully analyzed the image without errors.
`live`	Boolean	`true` if the primary detected face is determined to be a live person.
`verdict`	String	Human-readable verdict for the primary face. Possible values: `"live"`, `"spoof"`.
`score`	Float	The liveness confidence score for the primary face (0.0 – 1.0). Higher values indicate greater confidence of liveness.
`reason`	String	Reason code associated with the verdict (e.g., `"ok"`).
`face_count`	Integer	Total number of faces detected in the submitted image.
`threshold`	Float	The liveness score threshold used to determine the verdict. Scores above this value are classified as live.
`frame`	Object	Dimensions of the analyzed image frame.
`frame.width`	Integer	Width of the input image in pixels.
`frame.height`	Integer	Height of the input image in pixels.
`faces`	Array	Array of face objects. Each element contains detection and liveness data for one detected face.

`faces[]` Object Fields

Parameter	Type	Description
`bbox`	Object	Bounding box of the detected face within the frame.
`bbox.x`	Integer	X-coordinate (pixels) of the top-left corner of the bounding box.
`bbox.y`	Integer	Y-coordinate (pixels) of the top-left corner of the bounding box.
`bbox.width`	Integer	Width of the bounding box in pixels.
`bbox.height`	Integer	Height of the bounding box in pixels.
`detection_score`	Float	Confidence score for face detection (0.0 – 1.0). Higher values indicate a more confidently detected face.
`liveness_score`	Float	Liveness confidence score for this specific face (0.0 – 1.0).
`antispoof_score`	Float	Anti-spoofing confidence score for this face (0.0 – 1.0). Higher values indicate lower probability of a spoofing attempt.
`is_live`	Boolean	`true` if this specific face passed the liveness check.

Example Successful Response

{
  "data": {
    "client_id": "face_liveness_v5_YbookLSDhSoVRtsCRvtO",
    "detail": {
      "ok": true,
      "live": true,
      "verdict": "live",
      "score": 0.833,
      "reason": "ok",
      "face_count": 1,
      "threshold": 0.7,
      "frame": {
        "width": 1896,
        "height": 2735
      },
      "faces": [
        {
          "bbox": {
            "x": 609,
            "y": 1009,
            "width": 852,
            "height": 853
          },
          "detection_score": 0.9995,
          "liveness_score": 0.833,
          "antispoof_score": 0.9978,
          "is_live": true
        }
      ]
    }
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

401 Unauthorized

400 Bad Request

{
  "status_code": 401,
  "success": false,
  "message": "Authentication credentials were not provided or are invalid.",
  "message_code": "unauthorized"
}

Returned when the Authorization header is missing, malformed, or contains an expired/invalid JWT token. Ensure you are using the correct token for the target environment (sandbox vs. production).

Integration Best Practices

Security Recommendations

Protect your JWT Token: Never expose your Bearer token in client-side code, public repositories, or logs. Store it in server-side environment variables or a secrets manager.

Use HTTPS exclusively: All API calls must be made over HTTPS. Never transmit tokens or biometric data over plain HTTP.

Rotate tokens regularly: Implement a token rotation policy. Revoke and regenerate tokens if a breach is suspected.

Scope API access: Use separate API credentials for sandbox testing and production deployments to prevent accidental cross-environment data leakage.

Minimize data retention: Do not store raw face images beyond the time required for the liveness check. Comply with applicable biometric data regulations.

User Experience Guidelines

Image Quality Guidance: Instruct users to submit well-lit, front-facing photos with minimal obstructions. Poor image quality is the leading cause of low detection_score and failed analyses.

Threshold Tuning: The default threshold is 0.7. For high-security applications, consider raising the threshold. For more permissive flows, a lower value may improve conversion rates — always balance security and UX.

Graceful Failure Handling: When live is false or face_count is 0, provide users with actionable feedback (e.g., "Please ensure your face is clearly visible and try again") rather than displaying raw error messages.

Multi-Face Awareness: If face_count > 1, prompt the user to ensure only one person is in frame during the liveness check to avoid ambiguous verdicts.

Timeout & Retry Logic: Implement a request timeout of at least 15 seconds and a retry mechanism (with exponential backoff) for transient 5xx errors.

Code Samples

cURL

Python

Node.js

Related APIs

Face Match API: Compares two face images to determine if they belong to the same individual. Commonly used alongside liveness detection for full biometric verification.

OCR ID Card API: Extracts text fields from government-issued identity documents. Often paired with liveness to complete a KYC flow.

Aadhaar OCR API: Extracts structured data from Aadhaar cards. Integrate with liveness detection for compliant Aadhaar-based eKYC.

Passport OCR API: Parses Machine Readable Zone (MRZ) data from passports. Use with liveness checks for international identity verification.

Video Liveness API: Performs liveness detection on short video clips for enhanced anti-spoofing assurance in high-security environments.

Compliance and Legal Considerations

Biometric Data Regulations: Face liveness data is classified as biometric personal data under several regulations including GDPR (EU), PDPA (various APAC countries), and state-level biometric privacy laws (e.g., BIPA in Illinois, USA). Ensure you have appropriate legal basis (consent, legitimate interest, etc.) before collecting and processing such data.

Data Localization: Depending on your jurisdiction, biometric data may be subject to data residency requirements. Confirm whether the Surepass infrastructure supporting your environment complies with applicable data localization laws.

User Consent: Always obtain explicit, informed consent from individuals before capturing and submitting their facial data for liveness analysis. Maintain records of consent for audit purposes.

Retention Policies: Do not retain biometric images or scores beyond the immediate need for verification. Implement automated deletion policies aligned with your data protection obligations.

Purpose Limitation: Use the liveness check API exclusively for the stated verification purpose. Secondary use of liveness scores for profiling, targeting, or any unrelated processing is prohibited under most data protection frameworks.

Audit Logging: Retain API call logs (excluding raw image data) including client_id, timestamps, and verdicts for a minimum period as required by your compliance framework to support audit and dispute resolution.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "client_id": "face_liveness_v5_YbookLSDhSoVRtsCRvtO", "detail": { "ok": true, "live": true, "verdict": "live", "score": 0.833, "reason": "ok", "face_count": 1, "threshold": 0.7, "frame": { "width": 1896, "height": 2735 }, "faces": [ { "bbox": { "x": 609, "y": 1009, "width": 852, "height": 853 }, "detection_score": 0.9995, "liveness_score": 0.833, "antispoof_score": 0.9978, "is_live": true } ] } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Face Liveness V5

Face Liveness Detection V5#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request (File Upload)#

Example Request (URL Input)#

Example Request (PDF File Upload)#

Response Parameters#

Top-Level Fields#

data.detail Fields#

faces[] Object Fields#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses