Get Report

Endpoint Overview

POST /api/v1/liveness-sdk/get-report

Description

The Get Report API endpoint retrieves detailed liveness verification results for a specific client session. This endpoint provides comprehensive information about a completed liveness check, including verification status, timestamps for different stages of the verification process, and access to the recorded verification video. It allows developers to access the results of liveness detection processes performed through the Surepass SDK.

Key Benefits

Retrieve complete verification data including video evidence and timestamps

Access detailed status information for each verification step (face detection, eye blink, movement detection)

Verify the integrity and completion of liveness checks

Integrate verification results into your application's user journey

Use Cases

Financial Services

Healthcare

Government Services

Retrieve liveness verification results during customer onboarding for regulatory compliance

Access verification data for audit trails in banking applications

Confirm identity verification completion before allowing account access

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

Request Body

Parameter	Type	Required	Description
client_id	String	Yes	Unique identifier for the liveness verification session

Example Request

{
    "client_id": "{{client_id}}"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the verification report data
data.client_id	String	Unique identifier for the liveness verification session
data.video_link	String	URL to access the recorded verification video
data.verification_status	String	Overall status of the verification process (e.g., "completed")
data.video_start_time	String	Unix timestamp when video recording started
data.eye_blink_status	Boolean	Whether eye blink detection was successful
data.latitude	String	Geographic latitude where verification occurred (if available)
data.movement_detection_time	String	Unix timestamp when movement was detected
data.movement_detection_status	Boolean	Whether movement detection was successful
data.eye_blink_time	String	Unix timestamp when eye blink was detected
data.face_detection_status	Boolean	Whether face detection was successful
data.face_detection_time	String	Unix timestamp when face was detected
data.video_end_time	String	Unix timestamp when video recording ended
data.longitude	String	Geographic longitude where verification occurred (if available)
status_code	Integer	HTTP status code of the response
success	Boolean	Whether the API request was successful
message	String or null	Additional information about the response (null if successful)
message_code	String	Code indicating the result of the request

Example Successful Response

{
    "data": {
        "client_id": "liveness_sdk_onCIadgagadsNnMbBxZ",
        "video_link": "https://link-to-video.com",
        "verification_status": "completed",
        "video_start_time": "1623934721",
        "eye_blink_status": true,
        "latitude": "",
        "movement_detection_time": "1623934725",
        "movement_detection_status": true,
        "eye_blink_time": "1623934728",
        "face_detection_status": true,
        "face_detection_time": "1623934721",
        "video_end_time": "1623934737",
        "longitude": ""
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Authentication Error

{
    "data": null,
    "status_code": 400,
    "success": false,
    "message": "Invalid client_id provided",
    "message_code": "invalid_client_id"
}

This error occurs when the provided client_id does not exist or is in an invalid format.

Integration Best Practices

Security Recommendations

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

Implement proper error handling to avoid exposing sensitive information

Validate the verification status before proceeding with user authentication

Implement IP restrictions for API access in production environments

User Experience Guidelines

Provide clear feedback to users about the verification process status

Implement appropriate loading states while fetching verification results

Handle verification failures gracefully with clear instructions for retry

Consider implementing a caching mechanism for frequently accessed reports

Code Samples

cURL

Python

Node.js

Related APIs

Liveness SDK Initialization API: Creates a new liveness verification session

Liveness SDK Webhook Configuration: Configures webhook notifications for verification events

User Verification Status API: Checks the overall verification status of a user

Compliance and Legal Considerations

When implementing liveness verification, ensure compliance with data protection regulations such as GDPR, CCPA, or local biometric data laws. Proper user consent should be obtained before initiating liveness checks, and verification data should be stored securely with appropriate retention policies. Consider implementing data minimization practices and providing users with the ability to request deletion of their verification data.

{ "data": { "client_id": "liveness_sdk_onCIadgagadsNnMbBxZ", "video_link": "https://link-to-video.com", "verification_status": "completed", "video_start_time": "1623934721", "eye_blink_status": true, "latitude": "", "movement_detection_time": "1623934725", "movement_detection_status": true, "eye_blink_time": "1623934728", "face_detection_status": true, "face_detection_time": "1623934721", "video_end_time": "1623934737", "longitude": "" }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Get Report

Get Report#

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

Get Report

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples