NACH Extraction API

The following document highlights the details of the NACH Extraction API.

API Description

Objective

The NACH Extraction API takes input as an image of pre-filled NACH templates and returns a JSON with the values filled in the image.

Input	Output
NACH template image (JPG, TIFF, PNG)	Extracted NACH mandate details including UMRN, bank information, account details, mandate details, and validation results. A complete list of details returned by the API is provided under the Success Response Details section

API URL

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

API Endpoint

nach_extraction

Overview

The NACH Extraction 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 NACH Extraction API.

Parameter	Mandatory or Optional	Description	Allowed Values
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.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the parameters required for the NACH Extraction API's request form:

Parameter	Mandatory or Optional	Description
image	Mandatory	NACH template image file (JPG, TIFF, PNG, max 10Mb)
templateVersion	Optional	Template version (v1, v2, v3). Default: v3
enableOutputJPEG	Optional	Enable JPEG output (yes/no). Default: no
enableOutputTIF	Optional	Enable TIF output (yes/no). Default: no
enableOutputPDF	Optional	Enable PDF output (yes/no). Default: no

Things to ensure

• Only use an image with markers, otherwise it would throw HTTP error 422

Request

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

curl --location 'https://ind-engine.thomas.hyperverge.co/v1/nach_extraction' \
--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_nach_image>"' \
--form 'enableOutputJPEG="no"' \
--form 'enableOutputTIF="no"' \
--form 'enableOutputPDF="no"' \
--form 'templateVersion="v3"'

Success Response

The following code snippet demonstrates a success response from the NACH Extraction API:

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "type": "nach",
        "details": {
            "UMRN": {
                "conf": 0.95,
                "value": "<UMRN_Number>",
                "to-be-reviewed": "no"
            },
            "nachDate": {
                "conf": 0.98,
                "value": "<NACH_Date>",
                "to-be-reviewed": "no"
            },
            "sponsorCode": {
                "conf": 0.92,
                "value": "<Sponsor_Code>",
                "to-be-reviewed": "no"
            },
            "utilityCode": {
                "conf": 0.96,
                "value": "<Utility_Code>",
                "to-be-reviewed": "no"
            },
            "bankName": {
                "conf": 0.94,
                "value": "<Bank_Name>",
                "to-be-reviewed": "no"
            },
            "accountType": {
                "conf": 0.88,
                "value": "<Account_Type>",
                "to-be-reviewed": "no"
            },
            "IFSCCode": {
                "conf": 0.97,
                "value": "<IFSC_Code>",
                "to-be-reviewed": "no"
            },
            "MICR": {
                "conf": 0.93,
                "value": "<MICR_Code>",
                "to-be-reviewed": "no"
            },
            "companyName": {
                "conf": 0.91,
                "value": "<Company_Name>",
                "to-be-reviewed": "no"
            },
            "frequency": {
                "conf": 0.89,
                "value": "<Frequency>",
                "to-be-reviewed": "no"
            },
            "amountInNumber": {
                "conf": 0.95,
                "value": "<Amount_Number>",
                "to-be-reviewed": "no"
            },
            "amountInWords": {
                "conf": 0.87,
                "value": "<Amount_Words>",
                "to-be-reviewed": "no"
            },
            "debitType": {
                "conf": 0.96,
                "value": "<Debit_Type>",
                "to-be-reviewed": "no"
            },
            "startDate": {
                "conf": 0.94,
                "value": "<Start_Date>",
                "to-be-reviewed": "no"
            },
            "endDate": {
                "conf": 0.92,
                "value": "<End_Date>",
                "to-be-reviewed": "no"
            },
            "untilCanceled": {
                "conf": 0.90,
                "value": "<Until_Canceled>",
                "to-be-reviewed": "no"
            },
            "NACHType": {
                "conf": 0.93,
                "value": "<NACH_Type>",
                "to-be-reviewed": "no"
            },
            "phoneNumber": {
                "conf": 0.88,
                "value": "<Phone_Number>",
                "to-be-reviewed": "no"
            },
            "emailId": {
                "conf": 0.85,
                "value": "<Email_ID>",
                "to-be-reviewed": "no"
            },
            "reference1": {
                "conf": 0.86,
                "value": "<Reference_1>",
                "to-be-reviewed": "no"
            },
            "reference2": {
                "conf": 0.84,
                "value": "<Reference_2>",
                "to-be-reviewed": "no"
            },
            "signaturePresentPrimary": {
                "conf": 0.91,
                "value": "<Yes_No>",
                "to-be-reviewed": "no"
            },
            "signaturePresentSecondary": {
                "conf": 0.89,
                "value": "<Yes_No>",
                "to-be-reviewed": "no"
            },
            "signaturePresentTertiary": {
                "conf": 0.87,
                "value": "<Yes_No>",
                "to-be-reviewed": "no"
            },
            "primaryAccountHolder": {
                "conf": 0.93,
                "value": "<Primary_Account_Holder_Name>",
                "to-be-reviewed": "no"
            },
            "secondaryAccountHolder": {
                "conf": 0.85,
                "value": "<Secondary_Account_Holder_Name>",
                "to-be-reviewed": "no"
            },
            "tertiaryAccountHolder": {
                "conf": 0.82,
                "value": "<Tertiary_Account_Holder_Name>",
                "to-be-reviewed": "no"
            },
            "accountNumber": {
                "conf": 0.96,
                "value": "<Account_Number>",
                "to-be-reviewed": "no"
            }
        }
    }
}

Success Response Details

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

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The HTTP status code returned for the request
result	object	Contains the extracted details from the NACH template image
type	string	The type of document processed (nach)
details	object	Contains the extracted NACH mandate information with confidence scores
UMRN	object	The Unique Mandate Reference Number with confidence score and review flag
nachDate	object	The NACH mandate date with confidence score and review flag
sponsorCode	object	The sponsor bank code with confidence score and review flag
utilityCode	object	The utility company code with confidence score and review flag
bankName	object	The name of the bank with confidence score and review flag
accountType	object	The type of account with confidence score and review flag
IFSCCode	object	The IFSC code of the bank branch with confidence score and review flag
MICR	object	The MICR code of the bank branch with confidence score and review flag
companyName	object	The name of the company with confidence score and review flag
frequency	object	The frequency of the mandate execution with confidence score and review flag
amountInNumber	object	The amount in numerical format with confidence score and review flag
amountInWords	object	The amount in words with confidence score and review flag
debitType	object	The type of debit with confidence score and review flag
startDate	object	The start date of the mandate with confidence score and review flag
endDate	object	The end date of the mandate with confidence score and review flag
untilCanceled	object	The until canceled flag with confidence score and review flag
NACHType	object	The type of NACH mandate with confidence score and review flag
phoneNumber	object	The phone number with confidence score and review flag
emailId	object	The email ID with confidence score and review flag
reference1	object	The first reference number with confidence score and review flag
reference2	object	The second reference number with confidence score and review flag
signaturePresentPrimary	object	The primary signature presence indicator with confidence score and review flag
signaturePresentSecondary	object	The secondary signature presence indicator with confidence score and review flag
signaturePresentTertiary	object	The tertiary signature presence indicator with confidence score and review flag
primaryAccountHolder	object	The name of the primary account holder with confidence score and review flag
secondaryAccountHolder	object	The name of the secondary account holder with confidence score and review flag
tertiaryAccountHolder	object	The name of the tertiary account holder with confidence score and review flag
accountNumber	object	The account number with confidence score and review flag
conf	number	The confidence score for the extracted field (0-1)
value	string	The extracted value for the field
to-be-reviewed	string	The flag indicating if the field needs manual review (yes/no)

note

The response's field values reflect only the data recorded in the user's NACH template image. Fields with confidence scores below 75% are marked for review.

Failure Response

The following is a failure response from the NACH Extraction API:

{
    "status": "failure",
    "statusCode": "422",
    "error": "No NACH detected"
}

Error Responses

The following are some error responses from the NACH Extraction API:

Input Validation Error - Enum Values

{
    "message": "Input Validation Error: is not one of enum values: yes,no",
    "statusCode": 400,
    "status": "failure"
}

Input Validation Error - Template Version

{
    "message": "Input Validation Error: is not one of enum values: v1,v2,v3",
    "statusCode": 400,
    "status": "failure"
}

Missing Image

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

No NACH Detected

{
    "status": "failure",
    "statusCode": "422",
    "error": "No NACH detected"
}

Internal Server Error

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

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 Code	Error Message	Description
400	Input Validation Error: is not one of enum values: yes,no	The enableOutputJPEG, enableOutputTIF, or enableOutputPDF parameter is used but is not in [yes,no].
400	Input Validation Error: is not one of enum values: v1,v2,v3	The templateVersion parameter is used but is not in [v1,v2,v3].
400	API call requires one input image	The image is missing in the request.
422	No NACH detected	The image uploaded does not contain NACH markers.
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution.