Name Comparator

Endpoint Overview

POST /api/v1/ai/comparator/name

Description

The Name Comparator API provides intelligent name matching capabilities to identify potential matches between two name variations. It analyzes full names against short or alternate versions to determine if they likely refer to the same individual. The API evaluates various matching patterns such as abbreviations, nicknames, misspellings, and partial matches, returning a confidence score with detailed justification for the match assessment.

Key Benefits

Accurately identify matches between full names and shortened versions or nicknames

Receive detailed match type classification with 12 different match categories

Get confidence scoring with justification to understand match quality

Improve user verification processes with intelligent name comparison

Use Cases

Financial Services

HR & Recruitment

Customer Onboarding

Verify customer identity during account opening by matching ID documents with application forms

Reconcile payment beneficiary names with account holder records

Screen customer names against watchlists with tolerance for variations

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	Bearer token authentication using JWT
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
name_1	String	Yes	Full name of the individual to be compared
name_2	String	Yes	Short or alternate name to compare against name_1

Example Request

{
    "name_1": "Rahul Gupta",
    "name_2": "Rahul"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the response data
data.client_id	String	Unique identifier for the API request
data.name_1	String	The first name provided in the request
data.name_2	String	The second name provided in the request
data.match_type	Array of Enum	Types of name match identified (see match types below)
data.name_similarity_confidence	Enum	Confidence level of the similarity between names
data.justification	String	Detailed explanation of the match determination
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the API call was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Match Types

no_match: Names do not match

abbreviated: One name is an abbreviation of the other

misspelled: Names match but with spelling differences

prefix: One name contains a prefix not in the other

suffix: One name contains a suffix not in the other

nickname: One name is a nickname of the other

alternate_spelling: Names match but use different spelling conventions

partial_match: One name is partially contained in the other

full_match: Names match completely

spacing_issue: Names match but have different spacing

different_order: Names contain the same components but in different order

short_name: One name is a shortened version of the other

Confidence Levels

very_high: Extremely confident in the match

high: Strongly confident in the match

moderate: Reasonably confident in the match

low: Limited confidence in the match

very_low: Minimal confidence in the match

Example Successful Response

{
    "data": {
        "client_id": "name_comparator_zgMvhhtvuVknJHqwhAjU",
        "name_1": "Deepak",
        "name_2": "Deepak",
        "match_type": [
            "full_match"
        ],
        "name_similarity_confidence": "very_high",
        "justification": "The names 'deepak' and 'deepak' are identical in spelling, order, and case, indicating a full match with very high confidence."
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Missing Parameters

Authentication Error

{
    "status_code": 400,
    "success": false,
    "message": "Required parameters missing",
    "message_code": "missing_parameters",
    "errors": ["name_1 is required", "name_2 is required"]
}

This error occurs when one or both of the required name parameters are missing from the request.

Integration Best Practices

Security Recommendations

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

Implement token refresh mechanisms to handle token expiration

Use HTTPS for all API communications to ensure data encryption in transit

Implement proper error handling to avoid exposing sensitive information

User Experience Guidelines

Present match confidence levels with appropriate visual indicators

Provide users with the justification when displaying potential matches

Allow manual override options when automated matching has low confidence

Consider implementing progressive matching that starts with strict criteria and relaxes as needed

Code Samples

cURL

Python

Node.js

Related APIs

Address Comparator API: Compares addresses to identify potential matches with confidence scoring

Document Verification API: Extracts and verifies information from identity documents

Face Matching API: Compares facial biometrics between two images for identity verification

Compliance and Legal Considerations

When implementing name matching for KYC or regulatory purposes, ensure your matching thresholds align with local regulatory requirements. Different jurisdictions may have varying standards for what constitutes a sufficient name match. This API should be used as part of a comprehensive identity verification strategy and not as the sole determinant for high-risk decisions.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/ai/comparator/name' \ --header 'Content-Type: application/json' \ --data-raw '{ "name_1": "Rahul Gupta", "name_2": "Rahul" }'

{ "data": { "client_id": "name_comparator_zgMvhhtvuVknJHqwhAjU", "name_1": "Deepak", "name_2": "Deepak", "match_type": [ "full_match" ], "name_similarity_confidence": "very_high", "justification": "The names 'deepak' and 'deepak' are identical in spelling, order, and case, indicating a full match with very high confidence." }, "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 ********************

Name Comparator

Name Comparator#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Match Types#

Confidence Levels#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Name Comparator

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Match Types

Confidence Levels

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples