Skip to main content

Signature Detection API

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

API Description​

Objective​

The Signature Detection API checks for a signature in an image and helps extract it by providing its bounding box* coordinates.

InputOutput
The image containing the user's signatureThe signature's bounding box coordinates
Did you know?
* Bounding Box

A bounding box is a rectangular border that completely encloses a detected signature on an image. It is defined by its width, height, and the coordinates of its top-left corner (left, top). This allows precise localization of the signature within the image. Check the Success Response section for a set of sample bounding box values.

API URL​

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

API Endpoint​

signatureDetection

Overview​

The Signature Detection 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 Detection API.

Headers​

HeaderMandatory / OptionalDescriptionInput Format
content-type MandatoryThis parameter defines the media type for the request payloadmultipart/form-data
appId MandatoryThe application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tabThis should be a unique value
appKey MandatoryThe application key shared by HyperVerge. You can find the details in the dashboard's credentials tabThis should be a unique value
transactionIdMandatoryA unique identifier for tracking a user journeyThis should be both unique and easily associated with the user's journey in your application(s)

Inputs​

Caution

Please upload uncompressed or raw images for more accurate detection and extraction. Compressed images may lead to inaccuracies.

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

ParameterMandatory / OptionalTypeDescriptionInput FormatDefault Value
imageMandatoryfileThe image or document for signature detection. The image file can be of JPEG or PNG format. It should contain only one signature for the detection process. The image should be clear and properly aligned to ensure accurate signature localization and extraction. The uploaded signature should ideally have a clear white background for the best performance.Image file (JPEG or PNG)Not Applicable
returnInputSignatureUrlOptionalstringIf set to "yes", the response returns the s3Url field with the link to access the input image. If set to "no", the response does not return the s3Url field.yes/nono
returnCroppedSignatureUrlOptionalstringIf set to "yes", the response returns the croppedS3Url field with the link to access a cropped image of the detected signature, excluding other elements of the original document. If set to "no", the response does not return the croppedS3Url field.yes/nono
returnDetectionDetailsOptionalstringIf set to "yes", the response returns the following additional fields for all the non-500 status responses: signatureDetected, score, and toBeReviewed.yes/nono
checkCroppedOptionalstringIf set to "yes", the Signature Detection API performs additional validation on the cropped signature image to ensure quality and accuracy. Signatures that touch the edges of the cropped image are rejected. If set to "no", only basic signature detection is performed.yes/nono

Request​

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

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/signatureDetection' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--form 'image=@"<Enter_the_Path_to_the_Image_or_Document>"' \
--form 'returnInputSignatureUrl="<yes_or_no>"' \
--form 'returnCroppedSignatureUrl="<yes_or_no>"' \
--form 'useCompression="<yes_or_no>"' \
--form 'returnDetectionDetails="<yes_or_no>"' \
--form 'checkCropped="<yes_or_no>"'

Success Response​

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

{
  "status": "success",
  "statusCode": 200,
  "metaData": {
      "requestId": "<Request_Identifier>",
    "transactionId": "<Transaction_Identifier>"
  },
  "result": {
      "message": "One signature detected",
      "boundingBox": {
          "width": 0.7068939208984375,
          "height": 0.6442266702651978,
          "left": 0.0950758308172226,
          "top": 0.11097365617752075
      }
  }
}

Success Response Details​

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

ParameterTypeDescription
statusstringThe status of the request
statusCodeintegerThe HTTP status code for the response
resultobjectThe JSON object containing the signature detection details
result.messagestringThe summary of the signature detection outcome
result.boundingBoxobjectThe coordinates of the detected signature
result.s3UrlstringThe URL of the input image
result.croppedS3UrlstringThe URL of the cropped image of the signature after detection
result.signatureDetectedstringIndicates whether a signature was detected (returned when returnDetectionDetails is "yes")
result.scorefloatThe detection score (returned when returnDetectionDetails is "yes")
result.toBeReviewedstringIndicates whether manual review is required (returned when returnDetectionDetails is "yes")

Failure Response​

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

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

Error Responses​

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

{
  "status": "failure",
  "statusCode": 400,
  "metaData": {
    "requestId": "<Request_Identifier>"
  },
  "error": {
    "message": "Multiple signatures detected"
  }
}

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 CodeError MessageError DescriptionError Resolution
400No signature detectedNo signature was detected in the uploaded imagePlease retake the image and try again. Ensure the uploaded image contains a clear signature
400Multiple signatures detectedMultiple signatures were detected in the uploaded imagePlease retake the image and try again. Ensure the uploaded image contains only one signature
400Unsupported Document FormatThe document format is not supportedPlease upload a JPEG or PNG image
400Invalid signature: Signature is cropped or touches the borderThis error occurs when the detected signature touches the edges of the image or is partially cropped, which can affect signature quality and validation accuracyEnsure the signature is fully contained within the image boundaries and does not touch the edges
401Missing/Invalid credentialsThe request is either missing the mandatory appId and appKey combination or has invalid valuesVerify and provide valid appId and appKey credentials
422Invalid Signature. Please upload the signature on a white paperThe signature is not on a white paper. It is mandatory to use a white background for signature detectionUpload the signature on a white background
422Invalid Signature. Ink color is not validThe wet signature has invalid ink color (red or green)Use black or blue ink for the signature
429Rate limit exceededYou have exceeded the configured limit on the number of transactions permitted in a minuteRetry the request after some time or contact the HyperVerge team if the issue persists
500Internal Server ErrorAn internal server error occurred while processing the requestCheck the request headers or contact the HyperVerge team for resolution
Was this helpful?
ON THIS PAGE
Ask AIBeta
Hi! How can I help?
Ask me anything about HyperVerge products, APIs, and SDKs.
Try asking: