Field Match API

API Description

Objective

The Field Match API, also referred to as the Text Match API or Name Match API, compares text values from different sources to identify similarities and differences. For example, it can compare a user's name entered in a form with a name extracted via optical character recognition (OCR) from an officially valid document (OVD).

This API supports the following types of field matching:

Rule-based field match:
- Uses fuzzy or approximate string matching for fields such as "name" and "address."
- Performs exact matching for fields like "date of birth" and "national ID number."
AI-based field match.

Input	Output
The two textual fields for comparison	The boolean match results

Benefits

The sample use-cases for the Text Match API involves matching:

the extracted OVD fields with the form inputs, or
the extracted OVD fields with the fields associated with a bank account, or
the form inputs with the fields associated with a bank account, or
the 'user edited OCR output' with 'original OCR output' for auto-fills.

Did you know?

For the India region specifically, the Text Match API can take care of complexities such as,

ignoring English honorifics like "Mr.", "Mrs." and "Dr.", or
ignoring native honorifics like "Smt." , "Shri" and "Shree", or
ignoring placeholder names or surnames like "Bhai","Kumar" and "Kumari", or
names that sound similar like "Puja" and "Pooja", or
names with the first and the last name interchanged, or
initials in a name (we only consider up to two characters).

API URL

https://ind-verify.hyperverge.co/api/matchFields

API Endpoint

matchFields

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and ﬁles as form-data through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity and access the API.

API Request Details

Method - `POST`

Headers

Parameter	Mandatory or Optional	Description	Accepted Values
content-type	Mandatory	The media type for the request payload.	application/json
appId	Mandatory	The Application ID provided by HyperVerge	This should be a unique value provided by HyperVerge.
appKey	Mandatory	The Application Key provided by HyperVerge	This should be a unique value provided by HyperVerge.
transactionId	Mandatory	A custom unique identifier for a user journey or transaction.	This should be a unique value configured by you.

Inputs

The following table outlines the input parameters required for any type of field match.

Parameter	Mandatory or Optional	Accepted Values	Default Value	Description
Category of the fields in comparison	Mandatory	Type: String	Not Applicable	Specifies the category of the two fields being compared. This helps the API implement the appropriate field match mechanism. Refer to the full list of supported field categories here.
`value1`	Mandatory	Type: String	Not Applicable	The first string value. This value will be compared with the `value2` parameter.
`value2`	Mandatory	Type: String	Not Applicable	The second string value. This value will be compared with the `value1` parameter.
`preferences`	Optional	Type: Object	Not Applicable	This object supports additional configurations for the field match process. The tables in the following sections provide more details about each configuration option.

Inputs for Rule-Based Match

Parameter	Mandatory or Optional	Accepted Values	Default Value	Description
`preferences.phonetic`	Optional	Type: Boolean String "yes" or "no"	`no`	If set to "yes", classifies similar sounding names as the same.
`preferences.removeSuffix`	Optional	Type: Boolean String "yes" or "no"	`no`	If set to "yes", removes native honorifics like "Smt." from the names.
`preferences.editDistance`	Optional	Type: Integer Range: [0, 2]	Not Applicable	Sets a tolerance limit for the match. It refers to a measure of the similarity or dissimilarity between two names measured in terms of the number of character-level operations. It is a count of the difference in characters between `value1` and `value2`. For example, an editDistance of 1 means that the names can differ by one character (e.g., "sanchayn" and "sanchayan"). If `editDistance` is set to 0: "sanchayn" and "sanchayan" will not match, as there is a one-character difference. If `editDistance` is set to 1: "sanchayn" and "sanchayan" will match, as they differ by only one character. Note: We recommend setting this to 1 for the best balance between strictness and flexibility in matching names.
`preferences.matchyob`	Optional	Type: Boolean String "yes" or "no"	`no`	info This parameter is only applicable for the `dob` category. If set to "yes", the API only considers the birth year when comparing two date of birth values and returns the result under the "dobyob" field. It is a match ("dobyob": true) if the birth year is the same for both.

Inputs for AI-Based Match

Parameter	Mandatory or Optional	Accepted Values	Default Value	Description
`preferences.returnScore`	Optional	Type: Boolean String `yes` or `no`	`no`	If set to "yes", it returns the confidence score associated with the match result. This parameter applies only when matching the field, `name`. Please contact the HyperVerge team for more details.

note

The returnScore parameter determines the matching logic:

If returnScore = "yes" → AI-based matching is performed, overriding rule-based parameters. The response includes a similarity score (e.g., 87%).

If returnScore = "no" → Rule-based matching is applied, returning a boolean match result (e.g., name = false).

Supported Field Categories

The API supports the following list of field categories for performing a match.

Parameter	Meaning	Default Match Type	Supported Match Types
name	Name	Direct Match	Fuzzy, Edit Distance, Direct
address	Address	Fuzzy Match	Fuzzy
aadhaar	Aadhaar ID	Direct Match	Direct
passport_num	Passport Number	Direct Match	Direct
voterid	Voter ID	Direct Match	Direct
pan_no	Permanent Account Number (PAN)	Direct Match	Direct
pincode	Pincode	Direct Match	Direct
phone	Phone Number	Direct Match	Direct
dob	Date of Birth	Direct Match	Direct
yob	Year of Birth	Direct Match	Direct
doi	Date of Issue	Direct Match	Direct
doe	Date of Expiry	Direct Match	Direct
doc	Date of Creation	Direct Match	Direct
gender	Gender	Direct Match	Direct
place_of_birth	Place of Birth	Direct Match	Direct
place_of_issue	Place of Issue	Direct Match	Direct
relation	Relation	Direct Match	Direct
age	Age	Direct Match	Direct

Request

The following code shows a standard curl request for the API.

returnScore Enabled
Other Preferences Params Enabled - 1
Multiple Preferences Params Enabled - 2
matchYob Enabled

curl --location --request POST 'https://ind-verify.hyperverge.co/api/matchFields' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "name": {
        "value1": "Sanchayan S",
        "value2": "Sanchayan Sarkar",
        "preferences": {
            "returnScore": "yes"
        }
    },
    "address": {
        "value1": "<Address_source_1>",
        "value2": "<Address_source_2>"
    }
}'

curl --location --request POST 'https://ind-verify.hyperverge.co/api/matchFields' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "name": {
        "value1": "Sanchayan S",
        "value2": "Sunshine S",
        "preferences": {
            "phonetic": "yes",
            "removeSuffix": "yes",
            "editDistance": 1
        }
    },
    "address": {
        "value1": "<Address_source_1>",
        "value2": "<Address_source_2>"
    }
}'

curl --location --request POST 'https://ind-verify.hyperverge.co/api/matchFields' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
  "name": {
      "value1": "Mr.Sanchayan S",
      "value2": "Sunshine S",
      "preferences": {
          "phonetic": "no",
          "removeSuffix": "yes",
          "editDistance": 1
      }
  },
  "address": {
      "value1": "<Address_source_1>",
      "value2": "<Address_source_2>"
  }
}'

curl --location --request POST 'https://ind-verify.hyperverge.co/api/matchFields' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "dob": {
        "value1": "17-11-2001",
        "value2": "17-12-2001",
        "preferences": {
            "matchYob":"yes"
        }
    }
}'

Success Responses

Response for Request 1 - returnScore Enabled
Response for Request 2
Response for Request 3
Response for Request 4 - matchyob Enabled

The following is a response with all matching fields.

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "address": true,
        "nameScore": 0.85,
        "name": true,
        "all": true
    }
}

{
  "status": "success",
  "statusCode": "200",
  "result": {
      "name": true,
      "address": true,
      "all": true
  }
}

{
  "status": "success",
  "statusCode": "200",
  "result": {
      "name": false,
      "address": true,
      "all": false
  }
}

The following is a response with the "matchyob" parameter set to yes.

{
  "status": "success",
  "statusCode": "200",
  "result": {
      "dobyob": true,
      "dob": false,
      "all": false
  }
}

Success Response Details

Object	Field	Description
result	all	This is `true` when all the fields match their corresponding comparison fields.

Error Responses

The following are some error responses for the API.

Server Error
Rate Limit Error

{
  "status": "failure",
  "statusCode": "500",
  "error": "Internal Server Error"
}

{
  "status": "failure", 
  "statusCode": "429", 
  "error": "Rate limit error"
}

Failure and Error Response Details

A failure or error response contains a failure status with a relevant status code and error message. The following table lists all the failure and error responses.

Status Code	Error Message	Error Description
400	Corresponding Error Message	The request body is invalid. Please recheck and try again.
429	Rate limit exceeded	You have exceeded the configured rate limit for transactions per minute.
500/501	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution.
503	Server busy	Please retry the request in some time or contact the HyperVerge team for resolution.

API Description​

Objective​

Benefits​

API URL​

API Endpoint​

Overview​

Authentication​

API Request Details

Method - POST

Headers

Inputs​

Inputs for Rule-Based Match​

Inputs for AI-Based Match​

Supported Field Categories​

Request​

Success Responses​

Success Response Details​

Error Responses​

Failure and Error Response Details​