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 |