PDF Generator API

This document highlights the PDF Generator API details.

API Description

Objective

The PDF Generator API generates a redirection link required for Aadhaar OTP-based eSign processes. The API facilitates digital signatures for document signing and redirection.

Input	Output
The invitee details such as their name, phone and email	The redirection link for Aadhaar OTP-based eSign, along with the document ID, signer email, status code, and signer name

Note

An invitee is the individual whose Aadhaar-based digital signature is required on the document

API URL

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

API Endpoint

pdfGenerator

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.

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
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 complete information on all the input parameters for the API.

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
templateId	The unique Template ID each user	Optional info To be entered when the PDF is generated in-house	Not Applicable	Not Applicable
inviteeName	The name of the signer	Mandatory	Not Applicable	Not Applicable
inviteePhone	The phone number of the signer	Optional	Not Applicable	Not Applicable
inviteeEmail	The email ID of the signer	Optional	Not Applicable	Not Applicable
stampSeries	The series of stamps, if they are being utilized in the journey	Optional	Not Applicable	Not Applicable
eSignHintMessage		Mandatory	Not Applicable	Not Applicable
coordinates	The Coordinates for signing location on the PDF document	Optional info To be entered when the PDF isn't generated in-house	Format: "x1": 0, "x2": 50, "y1": 0, "y2": 50, "page": 1	Not Applicable
file	The file in Base64 format, used when the PDF is not generated by the system.	Optional info To be entered when the PDF isn't generated in-house	Not Applicable	Not Applicable

Request

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

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/pdfGenerator' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "templateId": "<Enter_the_unique_template_ID>",
    "inviteeName": "<Enter_the_name>",
    "inviteePhone": "<Enter_the_phone_number>",
    "inviteeEmail": "<Enter_the_email_address>",
    "stampSeries": "<Enter_the_stamp_series>",
    "eSignHintMessage": "<Enter_the_eSign_hint_message>"
}'

Success Response

The following is a success response from the API:

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "data": {
      "signUrl": "<Redirection_Link_For_Aadhaar_OTP_eSign>",
      "documentId": "<Document_Identifier>",
      "email": "<Email_of_the_Signer>",
      "name": "<Name_of_the_Signer>",
      "phone": "<Phone_Number_of_the_Signer>"
    }
  }
}

Success Response Details

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

Parameter	Type	Description
statusCode	integer	The status code of the response
metaData	object	The metadata associated with the request
metaData.requestId	string	A unique identifier for the request
metaData.transactionId	string	A unique identifier for the transaction
result	object	The result object containing the response data
result.data	object	The data related to the sign URL and document details
result.data.signUrl	string	The URL for signing the document
result.data.documentId	string	The unique identifier for the document
result.data.email	string	The email address of the person to sign the document
result.data.name	string	The name of the person to sign the document
result.data.phone	string	The phone number of the person to sign the document

Error Response Samples

The following are some sample error responses from the API.

Input Validation Error

{
  "status": "failure",
  "statusCode": "400",
  "result": {
    "error": {
      "message": "Required file input is missing"
    }
  }
}

Missing/Invalid Credentials

{
  "status": "failure",
  "statusCode": "400",
  "result": {
    "error": {
      "message": "Error while parsing file input"
    }
  }
}

Internal Server Error

{
  "status": "failure",
  "statusCode": "500",
  "result": {
    "error": {
      "message": "Unknown error while parsing inputs"
    }
  }
}

Error Response Details

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

Status Code	Error Message	Error Description
400	Required file input is missing	The request is missing the required file input
400	Error while parsing file input	The system encountered an issue while parsing the file input
500	Unknown error while parsing inputs	The request failed due to an unknown error during input parsing
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution
500	PDF generation failed	The system failed to generate the requested PDF
503	External vendor downtime	The external vendor is currently down. Error code: EXTERNAL_DOWNTIME