Pay Slip OCR API

The following document highlights the details of the Pay Slip OCR API.

API Description

Objective

The Pay Slip OCR API extracts information from a user's payslip or salary slip using optical character recognition (OCR) and returns the extracted data in a JSON format.

Input	Output
An image or PDF file of the user's payslip document	The pay slip data extracted from the document and converted into a JSON format. The complete list of output fields is provided under the Success Response Details section.

API URL

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

API Endpoint

readINDPayslip

Overview

The Pay Slip OCR 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 Pay Slip OCR 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
transactionId	Mandatory	Unique ID for the customer journey	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 Pay Slip OCR API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
image	Mandatory	file	The image file of the user's pay slip	Image file (JPEG, JPG, PNG) or PDF	Not Applicable

Request

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

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/readINDPayslip' \
--header 'appid: <Enter_the_appId-Shared-by-HyperVerge>' \
--header 'appkey: <Enter_the_appKey-shared-by-HyperVerge>' \
--header 'transactionId : <Enter_the_Transaction_ID>' \
--form 'image=@"<path_to_image_file>"'

Document Sample

The following is a Pay Slip or Salary Slip Document:

Success Response

The following code snippet demonstrates a success response from the Pay Slip OCR API:

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "details": [
      {
        "fieldsExtracted": {
          "employerName": {
            "value": "<Employer_Name>"
          },
          "monthOfSalarySlip": {
            "value": "<Month_Of_Salary_Slip>"
          },
          "yearOfSalarySlip": {
            "value": "<Year_Of_Salary_Slip>"
          },
          "employeeDesignation": {
            "value": "<Employee_Designation>"
          },
          "employeeName": {
            "value": "<Employee_Name>"
          },
          "employeeID": {
            "value": "<Employee_ID>"
          },
          "employeePANNumber": {
            "value": "<Employee_PAN_Number>"
          },
          "employeeUANNumber": {
            "value": "<Employee_UAN_Number>"
          },
          "employeeDateOfJoining": {
            "value": "<Employee_Date_Of_Joining_in_DD/MM/YYYY_Format>"
          },
          "baseSalary": {
            "value": "<Base_Salary_in_INR>"
          },
          "grossSalary": {
            "value": "<Gross_Salary_in_INR>"
          },
          "netSalary": {
            "value": "<Net_Salary_in_INR>"
          },
          "bonus": {
            "value": "<Bonus_Amount_in_INR>"
          },
          "incentive": {
            "value": "<Incentive_Amount_in_INR>"
          },
          "pfAccountNumber": {
            "value": "<PF_Account_Number>"
          },
          "pfDeducted": {
            "value": "<PF_Deducted_Yes_Or_No>"
          },
          "pfDeductionAmount": {
            "value": "<PF_Deduction_Amount_in_INR>"
          },
          "professionalTaxAmount": {
            "value": "<Professional_Tax_Amount_in_INR>"
          },
          "incomeTaxAmount": {
            "value": "<Income_Tax_Amount_in_INR>"
          },
          "overtimeAllowance": {
            "value": "<Overtime_Allowance_in_INR>"
          },
          "nightShiftAllowance": {
            "value": "<Night_Shift_Allowance_in_INR>"
          },
          "netAppraisedSalary": {
            "value": "<Net_Appraised_Salary_in_INR>"
          }
        },
        "type": "<Document_Type>"
      }
    ]
  },
  "metadata": {
    "requestId": "<Request_ID>"
  }
}

Success Response Details

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

Parameter	Type	Description
status	string	The status of the request
statusCode	integer	The HTTP status code returned for the request
result	object	Contains the extracted details from the payslip
details	array	Contains the extracted fields with their values and confidence scores
fieldsExtracted	object	Contains all the extracted payslip fields and their values
employerName	string	The name of the employer
monthOfSalarySlip	string	The month for which the salary slip is generated
yearOfSalarySlip	string	The year for which the salary slip is generated
employeeDesignation	string	The designation of the employee
employeeName	string	The name of the employee
employeeID	string	The unique identifier for the employee
employeePANNumber	string	The 10-digit PAN of the employee
employeeUANNumber	string	The UAN number of the employee
employeeDateOfJoining	string	The date of joining of the employee
baseSalary	string	The base salary of the employee
grossSalary	string	The gross salary of the employee
netSalary	string	The net salary of the employee after deductions
bonus	string	The bonus amount for the employee
incentive	string	The incentive amount for the employee
pfAccountNumber	string	The PF account number of the employee
pfDeducted	string	Indicates if PF is deducted from the salary
pfDeductionAmount	string	The amount deducted for PF
professionalTaxAmount	string	The professional tax amount deducted
incomeTaxAmount	string	The income tax amount deducted from the salary
overtimeAllowance	string	The allowance for overtime work
nightShiftAllowance	string	The allowance for working night shifts
netAppraisedSalary	string	The net appraised salary of the employee
type	string	The type of document processed
metadata	object	Contains request and transaction identifiers
requestId	string	A unique identifier for the request

Failure Response

The following code snippet demonstrates a failure response from the Pay Slip OCR API:

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

Error Responses

The following are some error responses from the Pay Slip OCR API:

No Image Input

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

Image Size Exceeds Limit of 6MB

{
  "status": "failure",
  "statusCode": 400,
  "error": "Image size cannot be greater than 6MB"
}

Document Not Detected

{
  "status": "failure",
  "statusCode": 422,
  "error": "Document Not 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 Code	Error Message	Error Description	Error Resolution
400	API call requires one input image	The request does not include an input image, which is mandatory for processing.	Ensure the request includes the image parameter with a valid image or PDF file
400	Image size cannot be greater than 6MB	The provided image exceeds the maximum allowed size of 6MB.	Reduce the image file size to 6MB or less before submitting the request
422	Document Not Detected	The system was unable to detect any document in the provided image.	Ensure the image contains a clear and visible payslip document, or contact the HyperVerge team if the issue persists