Face Match

Endpoint Overview

POST /api/v1/face/face-match

Description

The Face Match API compares two facial images to determine if they belong to the same person. This endpoint analyzes biometric features from both images and returns a match status along with a confidence score. This powerful verification tool helps organizations confirm identity claims by comparing a live selfie against a reference photo from an ID document or database.

Key Benefits

Reduces identity fraud by verifying that the person presenting credentials is the rightful owner

Provides quantifiable confidence scores to help make informed verification decisions

Enables contactless, remote identity verification for digital onboarding processes

Integrates easily into existing KYC and authentication workflows

Use Cases

Financial Services

Government & Public Sector

Enterprise Security

Customer onboarding verification comparing selfie to ID document photo

Secure authentication for high-value transactions

Account recovery verification to prevent unauthorized 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_token>`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
selfie	Image	Yes	Image of selfie
selfie_2	Image	No	Image of selfie
id_card	Image	Yes	Image of Id Card

Example Request

selfie=@"/path/to/file"
selfie_2=@"/path/to/file"

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the face match results
data.match_status	Boolean	`true` if faces match, `false` if they don't
data.confidence	Number	Confidence score (0-100) indicating the strength of the match
message_code	String/null	Error code if applicable, null on success
message	String/null	Error message if applicable, null on success
status_code	Number	HTTP status code of the response
success	Boolean	Indicates if the API call was successful

Example Successful Response

{
    "data": {
        "match_status": true,
        "confidence": 82.87096405029297
    },
    "message_code": null,
    "message": null,
    "status_code": 200,
    "success": true
}

Possible Error Responses

Invalid Images

Authentication Error

{
    "data": null,
    "message_code": "INVALID_IMAGE",
    "message": "One or both images could not be processed. Please ensure valid facial images are provided.",
    "status_code": 400,
    "success": false
}

This error occurs when the system cannot detect a valid face in one or both of the provided images.

Integration Best Practices

Security Recommendations

Always use HTTPS for all API communications to ensure data encryption in transit

Implement proper token management, including secure storage and regular rotation

Apply rate limiting on your side to prevent abuse of the API

Validate and sanitize all input data before sending to the API

User Experience Guidelines

Provide clear instructions to users for taking quality selfies (good lighting, neutral expression, etc.)

Implement a user-friendly retry mechanism if the match fails due to image quality issues

Consider implementing a minimum confidence threshold appropriate for your security requirements

Display appropriate feedback to users based on match results and confidence scores

Code Samples

cURL

Python

Node.js

Related APIs

Face Liveness Detection: Verifies that a facial image is from a live person and not a spoof attempt

Document Face Extraction: Extracts facial images from identity documents for comparison

Face Authentication: Enables recurring authentication using facial recognition

ID Verification: Validates identity documents and extracts information for KYC processes

Compliance and Legal Considerations

When implementing facial recognition technology, ensure compliance with relevant data protection regulations such as GDPR, CCPA, or other local privacy laws. Obtain proper consent before collecting and processing biometric data, maintain appropriate data retention policies, and provide clear privacy notices to users about how their facial data will be used, stored, and protected.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Face Match

Face Match#

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 Match

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples