Skip to main content

KYB Documents OCR API

This document highlights the KYB document API details.

API Description​

Objective​

The KYB Documents OCR API extracts information from an image or PDF of a KYB Document and returns it in a JSON format. The API supports the following document types:

  • Shop and Establishment certificate
  • Udyam Certificate
  • GST certificate
  • Certificate of Incorporation
caution

This product might provide mixed results when used on other business documents. We recommend discussing it with the HyperVerge team before using it on other business documents.

InputOutput
An image, PDF, or S3 URL of a supported KYB document The KYB related information extracted from the image. The complete list of output fields is provided under the Success Response Details section.

API URL​

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

API Endpoint​

KYBDocumentsOCR

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 files 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 for accessing the API.

API Request Details

Method - POST

Headers

ParameterMandatory or OptionalDescriptionValid Values
content-type Mandatory This parameter defines the media type for the request payload.multipart/form-data
appId Mandatory Application ID shared by HyperVerge N/A. This is a unique value.
appKey MandatoryApplication Key shared by HyperVerge N/A. This is a unique value.
transactionIdMandatoryUnique ID for the customer journey. N/A. Any defined unique value mapped to a transaction in your business ecosystem.

Inputs​

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

ParameterMandatory or OptionalDescriptionAllowed ValuesValid Values
imageMandatory (optional if base64image is given)This is the KYB file on which you intended to run the OCR extractionThe file format can be JPG, JPEG, PNG, TIFF or PDFNot Applicable
outputImageBase64OptionalReturns the image in base64 format 'yes' or 'no'Not Applicable
base64imageMandatory (optional if image is given)Base64-encoded string representation of the KYB document. The API internally converts this string back to a file format before performing OCR extraction. Supported formats include JPEG, PNG, TIFF, or PDFs.string (base64 format of the image or the pdf)Not Applicable
responseTypeOptionalWhen set to 'v2', returns a flattened response structure with a single result object instead of an array. When empty or not provided, returns the standard array format. This parameter is useful for integration with systems that expect a single result object rather than an array.'v2' or emptyNot Applicable
s3UrlOptionalA valid S3 URL pointing to the KYB document stored in an S3 bucket. This parameter enables server-side resume functionality in workflows by allowing the API to directly access documents from cloud storage. When provided, the API will fetch the document from the specified S3 URL instead of processing a base64-encoded image. Supported document formats include JPEG, PNG, TIFF, and PDF.string (valid S3 URL)Not Applicable
info
The KYB identity cards are expected to have the information only on one side of the card. Only the first page of the document is considered as the input. In case the KYB input document has multiple pages, you will have to make individual requests to the API for each page of the document.

Request​

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

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/KYBDocumentsOCR' \
--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=@"<path_to_image_file>"' \
--form 'base64image="<base64_string_of_the_file>"' \
--form 'outputImageBase64="<yes_or_no>"' \
--form 'responseType="<v2_or_empty>"' \
--form 's3Url="<Enter_the_S3_URL>"'

Success Responses​

The following code snippets demonstrate success responses from the API:

1. Responses for different valid KYB documents when responseType parameter is empty : 
{
  "status": "success",
  "statusCode": "200",
  "result": [
    {
      "details": {
        "reg_no": {
          "value": "27** *********Z2",
          "conf": 0.93,
          "to-be-reviewed": "no"
        },
        "legal_name": {
          "value": "",
          "conf": 0,
          "to-be-reviewed": "yes"
        },
        "trade_name": {
          "value": "COLLECTION",
          "conf": 0.79,
          "to-be-reviewed": "no"
        },
        "business_constitution": {
          "value": "PROPRIETORSHIP",
          "conf": 0.99,
          "to-be-reviewed": "no"
        },
        "address": {
          "value": "<Masked_Address>",
          "conf": 0.94,
          "to-be-reviewed": "no"
        },
        "date_liability": {
          "value": "",
          "conf": 0,
          "to-be-reviewed": "yes"
        },
        "valid_from": {
          "value": "01/07/2017",
          "conf": 0.99,
          "to-be-reviewed": "no"
        },
        "valid_till": {
          "value": "",
          "conf": 0,
          "to-be-reviewed": "yes"
        },
        "type": {
          "value": "",
          "conf": 0,
          "to-be-reviewed": "yes"
        }
      },
      "base64Image": "base64_string",
      "type": "GST"
    }
  ],
  "requestId": "<Request_ID>"
}
2. Responses from the API, for different valid KYB documents when the value for responseType parameter is "v2" : 
{
  "status": "success",
  "statusCode": "200",
  "result": {
    "details": {
      "reg_no": {
        "value": "<masked>",
        "conf": 0.97,
        "to-be-reviewed": "no"
      },
      "legal_name": {
        "value": "<masked>",
        "conf": 0.99,
        "to-be-reviewed": "no"
      },
      "trade_name": {
        "value": "<masked>",
        "conf": 0.98,
        "to-be-reviewed": "no"
      },
      "business_constitution": {
        "value": "PROPRIETORSHIP",
        "conf": 0.99,
        "to-be-reviewed": "no"
      },
      "address": {
        "value": "<masked>",
        "conf": 0.75,
        "to-be-reviewed": "yes"
      },
      "date_liability": {
        "value": "<masked>",
        "conf": 0,
        "to-be-reviewed": "yes"
      },
      "valid_from": {
        "value": "<masked>",
        "conf": 0.99,
        "to-be-reviewed": "no"
      },
      "valid_till": {
        "value": "<masked>",
        "conf": 0.99,
        "to-be-reviewed": "no"
      },
      "type": {
        "value": "REGULAR",
        "conf": 0.99,
        "to-be-reviewed": "no"
      }
    },
    "base64Image": "base64_string",
    "type": "GST"
  }
}

Success Response Details​

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

ParameterTypeDescription
statusstringThe status of the API request
statusCodestring or integerThe HTTP status code for the API response
resultobject or arrayThe extracted details from the KYB document; returns an array of objects if responseType is empty, or a single object if responseType is set to v2
result.detailsobjectThe key-value pairs of extracted fields from the document, such as registration number, legal name, trade name, business constitution, address, and other document-specific fields
result.details.[field].valuestringThe extracted value for the specific field
result.details.[field].confnumberThe confidence score for the extracted value, ranging from 0 to 1
result.details.[field].to-be-reviewedstringIndicates if the extracted value should be manually reviewed; possible values are yes or no
result.base64ImagestringThe base64-encoded image of the document, returned if outputImageBase64 is set to yes
result.typestringThe type of KYB document detected, such as GST, ShopEstablishmentCertificate, MSME, or COI
requestIdstringThe unique identifier for the API request

Failure Response​

The following is a sample failure response where the API fails to detect a document from the image:

{
  "status": "failure",
  "statusCode": 422,
  "error": "No Document detected",
  "requestId": "<Request_ID>"
}

Error Responses​

The following are some error responses for the API:

{
  "status": "failure",
  "statusCode": "400",
  "error": "API call requires one input image",
  "requestId": "<Request_ID>"
}

Failure and Error Response Details​

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

Status CodeError MessageError Description
400No Image inputThe request missed the image input.
400More than 1 image inputThe request had more than one image file input. It expects only one file in the request.
400image size cannot be greater than 12MBThe image size is larger than the allowed limit.
422Document not detected from ImageThe API failed to detect a document in the image. Ensure that the image captures the document following the guidlines mentioned under the Input Image Guidelines section.
5xxInternal Server Error There was an error with HyperVerge's server. Please contact the HyperVerge team.
Was this helpful?
ON THIS PAGE
Ask AIBeta
Hi! How can I help?
Ask me anything about HyperVerge products, APIs, and SDKs.
Try asking: