Name Match

Endpoint Overview

POST /api/v1/utils/name-matching/

Description

The Name Matching API provides a powerful solution for comparing and evaluating the similarity between two names. It analyzes names using advanced algorithms to determine how closely they match, returning a numerical score and match status. This API supports both person names and company names, making it versatile for various identity verification and data validation scenarios.

Key Benefits

Accurate name comparison with nuanced scoring system for different match levels

Support for both individual and company name matching

Detailed match scoring with clear classification thresholds

Fast and reliable results for real-time verification workflows

Use Cases

Financial Services

HR & Recruitment

Data Management

KYC (Know Your Customer) verification during customer onboarding

Anti-money laundering (AML) screening against watchlists

Fraud detection by comparing application data with existing records

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
name_1	String	Yes	The first name to compare
name_2	String	Yes	The second name to compare
name_type	String	Yes	Type of name being compared (e.g., "person", "company")

Example Request

{
    "name_1": "Vishal",
    "name_2": "Rathore",
    "name_type": "person"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the match results
data.client_id	String	Unique identifier for this name matching request
data.name_1	String	The first name that was compared (may be normalized)
data.name_2	String	The second name that was compared (may be normalized)
data.match_score	Integer	Numerical score (0-100) indicating match quality
data.match_status	Boolean	`true` if considered a match, otherwise `false`
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the API call was successful
message	String or null	Additional information about the response (if any)
message_code	String	Code indicating the status of the operation

Example Successful Response

{
    "data": {
        "client_id": "name_compare_eBFubciRtZwweOzRutox",
        "name_2": "Rathore Vishal",
        "name_1": "Vishal Rathore",
        "match_score": 100,
        "match_status": true
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Match Score Classifications

The API uses the following scoring system to classify match quality:

Classification	Score Range	Description
Direct Match	100	Perfect match between the names
Good Partial Match	80-99	High confidence in the match with minor variations
Moderate Partial Match	60-79	Reasonable confidence in the match with notable differences
Poor Partial Match	34-59	Low confidence in the match with significant differences
No Match	0-33	Names are considered different

Possible Error Responses

Authentication Error

Validation Error

{
    "detail": "Authentication credentials were not provided or are invalid"
}

This error occurs when the JWT token is missing, expired, or invalid.

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

Consider implementing a threshold-based approach based on your use case (e.g., auto-approve at 80+, manual review at 60-79)

Display match scores to users in a meaningful way, such as with color-coded indicators

Provide clear feedback when names don't match, with suggestions for possible issues

Consider implementing retry logic with alternative name formats for borderline cases

Code Samples

cURL

Python

Node.js

Related APIs

Address Verification API: Validates and standardizes address information

Document Verification API: Extracts and verifies information from identity documents

Face Match API: Compares facial biometrics between two images

Compliance and Legal Considerations

When implementing name matching for KYC or regulatory purposes, ensure your match thresholds comply with relevant regulations such as AML, KYC, and GDPR requirements. Different jurisdictions may have specific requirements for identity verification processes. Consider consulting with compliance experts when determining appropriate match thresholds for your specific use case.

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/utils/name-matching/' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "name_1": "Vishal", "name_2": "Rathore", "name_type": "person" }'

{ "data": { "client_id": "name_compare_eBFubciRtZwweOzRutox", "name_2": "Rathore Vishal", "name_1": "Vishal Rathore", "match_score": 100, "match_status": true }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Name Match

Name Match#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Match Score Classifications#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Name Match

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Match Score Classifications

Possible Error Responses

Integration Best Practices

Code Samples