Signature Matching API

The following document highlights the details of the Signature Matching API.

API Description

Objective

The Signature Matching API compares two signature images to verify their authenticity and detect potential fraud, providing match scores and verification results.

Input	Output
Two images that can be signature images or documents containing signatures	The match scores of the images, verification results, and manual review recommendations

API URL

https://ind-engine.thomas.hyperverge.co/v1/signature_matching

API Endpoint

signature_matching

Overview

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

Method - POST

Authentication

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

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	multipart/form-data
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value

Inputs

Compliance Checks

The Signature Matching API performs compliance checks to validate signature image quality. A valid signature image must have:

• A plain white background
• Signature in black or blue ink only
• No other content or details in the background

When you submit a document image (instead of a clean signature image), the background may not be white and may contain other text or details surrounding the signature. In such cases, set the corresponding disableCompliance1 or disableCompliance2 parameter to "yes" to skip compliance validation for that image. This allows the API to process document-based signatures that don't meet the standard compliance requirements.

The following table provides the details of the parameters required for the Signature Matching API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
image1	Mandatory	file	The first image file, which can be a signature image or a document containing a signature	Image file (JPEG, JPG, or PNG)	Not Applicable
image2	Mandatory	file	The second image file, which can be a signature image or a document containing a signature	Image file (JPEG, JPG, or PNG)	Not Applicable
disableCompliance1	Optional	string	Disable compliance validation checks for image1. Set to "yes" if image1 is a document containing a signature (non-white background or additional content)	yes/no	no
disableCompliance2	Optional	string	Disable compliance validation checks for image2. Set to "yes" if image2 is a document containing a signature (non-white background or additional content)	yes/no	no
enableSignatureDetection	Mandatory	boolean	Enable signature detection flag. If set to true, it automatically performs signature detection inside the matching API and also matches the 2 images	true/false	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the Signature Matching API:

curl --location 'https://ind-engine.thomas.hyperverge.co/v1/signature_matching' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--form 'image1=@"<Enter_the_signature_image1>"' \
--form 'image2=@"<Enter_the_signature_image2>"' \
--form 'disableCompliance1="<yes/no>"' \
--form 'disableCompliance2="<yes/no>"'\
--form 'enableSignatureDetection="<yes/no>"'

Success Response

The following code snippet demonstrates a success response from the Signature Matching API:

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "score": <Match_Score>,
    "match": "<Match_Result>",
    "to_be_reviewed": "<Review_Status>"
  }
}

Success Response Details

The following table outlines the details of the success response from the Signature Matching API:

Parameter	Type	Description
status	string	The status of the request
statusCode	integer	The HTTP status code for the response
result	object	The JSON object containing the signature matching details
score	float	The match score between the two signatures
match	string	The match result indicating if signatures match
to_be_reviewed	string	The review status indicating if manual review is required

Failure Response

The following code snippet demonstrates a failure response from the Signature Matching API:

{
    "status": "failure",
    "statusCode": 400,
    "metaData": {
        "requestId": "<Request_ID>"
    },
    "error": {
        "message": "No signature detected"
    }
}

Error Responses

The following are some error responses from the Signature Matching API:

No Signature Detected

{
    "status": "failure",
    "statusCode": 400,
    "metaData": {
        "requestId": "<Request_ID>"
    },
    "error": {
        "message": "No signature detected"
    }
}

Multiple Signatures Detected

{
    "status": "failure",
    "statusCode": 400,
    "error": "Multiple signatures detected"
}

Unsupported Document Format

{
    "status": "failure",
    "statusCode": 400,
    "error": "Unsupported Document Format"
}

Missing/Invalid Credentials

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Rate Limit Exceeded

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

Internal Server Error

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

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 error responses:

Status Code	Error Message	Error Description	Error Resolution
400	No signature detected	No signature was detected in the uploaded image	Ensure the uploaded image contains a clear signature
400	Multiple signatures detected	Multiple signatures were detected in the uploaded image	Ensure the uploaded image contains only one signature
400	Unsupported Document Format	The document format is not supported, please upload a JPEG, JPG, PNG, or TIFF image	Upload the image in a supported format (JPEG, JPG, PNG, or TIFF)
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Verify and provide valid appId and appKey credentials
429	Rate limit exceeded	The rate limit of the Signature Matching API has been exceeded	Retry the request after some time or contact the HyperVerge team if the issue persists
500	Internal Server Error	Kindly check the request headers or contact the HyperVerge team for resolution.	Check the request headers or contact the HyperVerge team for resolution