Face Extract

Endpoint Overview

POST /api/v1/face/face-extract

Description

The Face Extraction API enables users to extract faces from uploaded images with high precision and efficiency. This endpoint isolates and extracts facial regions from images, providing a clean, cropped image containing only the detected face. The service handles various image qualities, lighting conditions, and face orientations to deliver reliable results for identity verification and facial recognition applications.

Key Benefits

Automated face detection and extraction from complex images

High-precision facial boundary detection for clean extraction

Fast processing suitable for real-time applications

Standardized output format for consistent downstream processing

Use Cases

Financial Services

Identity Verification

Security Applications

KYC verification during customer onboarding

Secure authentication for banking applications

Fraud prevention during account opening

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 `multipart/form-data` for image upload

Request Body

Parameter	Type	Required	Description
image	File	Yes	The image file containing faces to be extracted. Supported formats include JPEG, PNG, and BMP.

Example Request

Process Response

Response Parameters

Parameter	Type	Description
success	Boolean	Indicates if the request was successful
status_code	Integer	HTTP status code of the response
message	String	Human-readable message describing the result
message_code	String	Machine-readable code for the message
data	Object	Contains the extracted face information
data.client_id	String	Unique identifier for the extraction request
data.extracted_image	String	URL to access the extracted face image

Example Successful Response

{
    "data": {
        "client_id": "face_extract_wvHkLMWtgbYzSkacgReF",
        "extracted_image": "https://aadhaar-kyc-docs.s3.amazonaws.com/vishal.rathore.surepass/face/face_extract_wvHkLMWtgbYzSkacgReF/face_extract_1717752796757974.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

No Face Detected

Invalid Image Format

Authentication Error

{
    "success": false,
    "status_code": 400,
    "message": "No face detected in the image",
    "message_code": "no_face_detected"
}

Returned when the API cannot detect any faces in the uploaded image.

Integration Best Practices

Security Recommendations

Always use HTTPS for all API communications

Implement proper token management with regular rotation

Store extracted face images securely with appropriate access controls

Implement rate limiting to prevent abuse of the API

User Experience Guidelines

Provide clear instructions to users for optimal face image capture

Implement a fallback mechanism when face extraction fails

Consider implementing a preview feature to show users the extracted face

Include progress indicators during image upload and processing

Code Samples

cURL

Python

Node.js

Related APIs

Face Match API: Compare two face images for identity verification

Face Liveness Detection API: Verify if a face image is from a live person

Document Face Extract API: Extract faces specifically from identity documents

Compliance and Legal Considerations

When implementing face extraction functionality, ensure compliance with applicable data protection regulations such as GDPR, CCPA, or other regional privacy laws. Users should be informed about face data collection, processing, and storage. Implement appropriate data retention policies and provide mechanisms for users to request deletion of their facial data.

{ "data": { "client_id": "face_extract_wvHkLMWtgbYzSkacgReF", "extracted_image": "https://aadhaar-kyc-docs.s3.amazonaws.com/vishal.rathore.surepass/face/face_extract_wvHkLMWtgbYzSkacgReF/face_extract_1717752796757974.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM" }, "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 Extract

Face Extract#

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 Extract

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples