Face Extract

Endpoint Overview

POST /api/v1/face/face-extract

Description

The Face Extraction API enables users to extract faces from 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. You can provide the image via file upload, base64-encoded string, or a publicly accessible URL. 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

Flexible input options — upload a file, send a base64 string, or provide an image URL

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	Set to `multipart/form-data` for file upload, or `application/json` for base64 and URL inputs

Request Body

You must provide the image using one of the following three input methods. All three are marked as optional individually, but exactly one must be provided per request.

Parameter	Type	Required	Description
image	File	Optional	The image file containing faces to be extracted.
use_pdf	Boolean	No	True for PDF Inputs.
base64	String	Optional	Base64-encoded string of the image.
link	String	Optional	Publicly accessible URL pointing to the image. The URL must be directly accessible without authentication.

Input Requirement

While each input parameter is individually optional, you must provide exactly one of image, base64, or url in every request. Providing none or multiple inputs will result in an error.

Input Guidelines:

File Upload: Best for direct integrations where the image is available locally. Supports JPEG, PNG, and PDF formats.

Base64: Ideal for server-to-server integrations or when the image is already in memory. Ensure proper encoding without data URI prefixes.

URL: The URL must be publicly accessible and return a valid image response.

Example Requests

Option 1: File Upload (multipart/form-data)

Option 2: Base64

{
  "base64": "/9j/4AAQSkZJRgABAQEASABIAAD..."
}

Option 3: Link

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

Note: When using file upload, the request must use multipart/form-data encoding. When using base64 or URL, the request must use application/json encoding.

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

Invalid Input

Invalid URL

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 provided 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

When using base64 input, ensure the encoding is performed server-side to avoid exposing image data in client-side code

When using URL input, ensure the image URLs are from trusted sources and do not expose sensitive resources

User Experience Guidelines

Provide clear instructions to users for optimal face image capture

Implement a fallback mechanism when face extraction fails (e.g., retry with a different input method)

Consider implementing a preview feature to show users the extracted face

Include progress indicators during image upload and processing

For URL-based inputs, validate URL accessibility before submission to provide immediate feedback

For base64 inputs, validate the encoding format on the client side before making API calls

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. When using URL-based inputs, ensure that the image source complies with data residency requirements and that transmitting the URL to a third-party service is permitted under your data processing agreements.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/face/face-extract' \ --header 'Authorization: Bearer <token>' \ --form 'image=@""' \ --form 'use_pdf=""' \ --form 'base64=""' \ --form 'link=""'

{ "data": { "client_id": "face_extract_rrOBzcQtOuisxLbKFDIx", "extracted_image": "https://aadhaar-kyc-docs.s3.amazonaws.com/abndc/face/face_extract_rrOBzcQtOuisxLbKFDIx/face_extract_1773485113381704.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20260314%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20260314T104513Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=cc7ade8518572efed5fb7504482ae58fbecf07d3944ea17ade4f99e19c36ad8b" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Requests#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses