ITR OTP Authorisation

Introduction:

The Authorisation api is used to authorise the user in order to get the required data and create a session. Depending on the available userFlow, it supports the OTP or password or both flows. Once the authorisation is successful, the flow cannot be changed for the request ID.

POST /authorisation

This endpoint is used to initiate a request for an ITR form by providing a userName. Returns a requestId that patrons can use to fetch the ITR form.

Sample Curl:

curl --location 'https://api-preproduction.signzy.app/api/v3/itr/authorisation' \
--header 'Content-Type: application/json' \
--header 'Authorization: <authToken>' \
--data-raw '{
    "requestId": "12345a67-89b0-12c3-def4-5ghij67klmno",
    "otp": "123456"
}'

Input Parameters:

Parameter	Type	Description	Mandatory/Optional
requestId	string	The request ID generated in the generate reqeust ID api	Mandatory
otp	string	The 6 digit OTP received	Conditionally Mandatory
password	string	The password associated with the userName	Conditionally Mandatory
callbackUrl	string	The callback url to which the data must be posted	Conditionally Optional
itrDetailsRequired	array of strings	The details that are to be posted to the callback url. Accepted values : 'itr_form', 'itr_pull' 'itr_v' and 'form_26_as'	Conditionally Optional

range	number	1, 2 or 3.Default to 3	Conditionally Optional
pdfBase64	Boolean	Flag to get base64 version of itr pdf	Optional
callbackAuth	object	Header key/value pairs sent with the callback request	Optional

Note: callbackUrl and itrDetailsRequired either passed together or not passed at all.

Sample Response:

{
    "requestId": "12345a67-89b0-12c3-def4-5ghij67klmno",
    "userName": "<userName>",
    "userFlow": "otp",
    "sessionStatus": "OTP/password successful",
    "statusCode": "200",
    "messageCode": "Session successfully created"
}

Output Parameters:

Parameter	Type	Description
requestId	string	A unique identifier (UUID) assigned to the request. This requestId is generated and returned by the API.
userName	string	The userName entered.
userFlow	string	The userFlow lets the user know the chosen flow after the successful session creation
sessionStatus	string	Gives the status of the session.
statusCode	integer	The HTTP status code indicating the success or failure of the API request. In this case, the statusCode of 200 denotes a successful response.
messageCode	string	A code or identifier associated with the message. In this instance, the messageCode "Session successfully created" provides additional context about the success of the session creation.

Sample Errors

{
    "error": {
        "reason": "ERROR",
        "status": 400,
        "message": "The OTP entered is incorrect, Enter correct OTP.",
        "type": "Unauthorized",
        "statusCode": 401,
        "name": "error"
    }
}

CODE	MESSAGE
200	Request successful
409	Unable to fetch data from upstream
400	Bad Request - Mandatory parameters missing or Invalid inputs