Aditya Birla Finance Limited: Lender API V2 Integration
API Latest Version Release Date: 07/06/2021
Document Revision History
Revision Revised By Summary of modifications
Date
02/03/2021 Neil Haria –
[[Link]@[Link]]
07/06/2021 Urvish Lodaria Added new status codes for the
API and callbacks expected after
[[Link]@[Link]] Softcell fixes
02/07/2021 Neil Haria Added `abfl_application_id` in
callback response
[[Link]@[Link]]
Document Review History
Review Date Reviewed By Reviewed Version
Table of Contents
API Reference 3
Authentication 3
Request and Response 4
Standard Response codes 8
API Reference
The API will be organized around REST. Our API will have predictable, resource-oriented
URLs, and will use HTTP response codes to indicate API errors. Secure interaction with the
API from a client-side web application or backend code will be supported. JSON will be
returned by all API responses, including errors.
Any web programming language should be able to make and receive HTTP networking calls.
Authentication
All API calls will be authenticated using an X-AUTH-TOKEN passed in the header of the
request call. X-AUTH-TOKEN value in the header will be validated for correctness before
invoking the API backend. The token can be created by the credentials shared to the partner
at the time of integration.
Request and Response
Method Name decisionEngine
HTTP Method POST
URL (environment = UAT) [Link]
Headers X-AUTH-TOKEN
Sample Request Structure:
{
"source": "GROWW",
"accountId": "GROWW914258",
"productCode": "GROWW",
"customerReport": {
"kycInfo": {
"firstName": "RAJAN",
"middleName": "DEV",
"lastName": "TEST",
"mobile": "7385134103",
"email": "abfltestapplication123@[Link]",
"panNumber": "CBBAC2137E",
"gender": "F",
"dob": "1975-05-13",
"addressLine1": "56t",
"addressLine2": "Mumbai",
"addressLine3": "Maharashtra",
"city": "Mumbai",
"state": "Maharashtra",
"pincode": 400071
},
"loanApplicationRequest": {
"requestedLoanAmount": 50000.0,
"roi": "2.0",
"tenure": "12"
}
}
}
Input:
The request should contain the following parameters.
Parameter Name Mandatory/Non- Valid Values/Formats Type of variable and
mandatory field condition on it
source Mandatory - Allowed chars = ascii_lowercase + e.g. GROWW
ascii_uppercase
- Min length – 3
- Max length - 50
accountId Mandatory - Allowed chars = ascii_lowercase + Loan Application ID
ascii_uppercase + digits + ['_', ‘-‘]
- Min length – 3
- Max length - 50
productCode Mandatory - Allowed chars = ascii_lowercase +
ascii_uppercase + digits + [‘_’] e.g. GROWW
firstName Mandatory - Allowed chars = ascii_lowercase +
ascii_uppercase First Name
middleName Optional - Allowed chars = ascii_lowercase + Middle Name
ascii_uppercase
lastName Mandatory - Allowed chars = ascii_lowercase + Last Name
ascii_uppercase
mobile Mandatory - Allowed chars = digits 9000329031
- Min length – 10
- Max length - 10
email Mandatory - Alphanumeric string. Actual Email ID
- No special characters allowed
except
- `-`, `_`, `.`
panNumber Mandatory - Alphanumeric string. Actual PAN Number
- No special characters allowed
- Min length - 10
- Max length - 10
dob Mandatory - YYYY-MM-DD format Date of Birth
gender Mandatory - Allowed chars `M` (male)
- `M` (male) `F` (female)
- `F` (female) `O` (other)
- `O` (other)
requestedLoanAmount Mandatory - Numeric only Loan Amount
- Type (numeric)
addressLine1 Mandatory - Alphanumeric string. Address Line 1
- No special characters like,
‘,",--,//,!,#,*,(,),%,`,~ are
supported
addressLine2 Optional - Alphanumeric string. Address Line 2
- No special characters like,
‘,",--,//,!,#,*,(,),%,`,~ are
supported
addressLine3 Optional - Alphanumeric string. Address Line 3
- No special characters like,
‘,",--,//,!,#,*,(,),%,`,~ are
supported
city Mandatory - Allowed chars = ascii_lowercase + City
ascii_uppercase
state Mandatory - Allowed chars = ascii_lowercase + State
ascii_uppercase
-
pincode Mandatory - Numeric only Pin Code
- Type (numeric)
- Min length - 6
- Max length - 6
roi Mandatory - Numeric only with decimal Rate of Interest
support
- Type (string)
tenure Mandatory - Numeric only Tenure
- Type (string)
Headers:
Header Name Description Valid Values/Formats
X-AUTH-TOKEN X-AUTH-TOKEN to be generated and sent Alphanumeric string.
as per the credentials shared by the No special characters like,
business or technology team ‘,",--,//,!,#,*,(,),%,`,~ are
supported
Output:
Output json body structure for all possible HTTPS responses codes have already been defined in the
STANDARD RESPONSE CODES sections. Response json body will have the following fields –
a. responseStatus – (string) - (SUCCESS, ERROR).
b. error - (dictionary) (contains code, description and errorType for all non-successful responses).
Sample Response Json:
{'responseStatus': 'SUCCESS'}
Standard Response codes
HTTPS Code Response Type Meaning Response Body
200 Success Request was successfully {'responseStatus': 'SUCCESS'}
processed. ERROR_MESSAGE will
be blank in this case.
412 InProgress Request for same account is either {
Request/BRE in progress or decision is already "responseStatus": "ERROR",
decision is already made for the account "error": {
"code": "BUSINESS_RULE_E
made for the
RROR",
account "description": "Previous CE
request for this application is in
progress"
}
}
400 Invalid Request Body One of the validation errors *Scenarios under which
occurred. status code of 400 is
returned are described is
separate table below
500 Bad Gateway / An internal error from the server *Scenarios under which
Internal Server Error side. status code of 500 is
returned are described is
separate table below
*Scenarios under which status code of 400 is returned with an error message –
HTTPS Code Response Type Meaning Response Body
400 Invalid Request Json not in conformation with {
Body schema. "responseStatus": "ERROR",
"error": {
"code": "BAD_REQUEST",
"description": "dob missing",
"errorType": "INVALID_PAYLOAD"
}
}
400 Invalid Request Invalid text field characters. {
Body "responseStatus": "ERROR",
"error": {
"code": "BAD_REQUEST",
"description": "dob is not valid",
"errorType": "INVALID_PAYLOAD"
}
}
*Scenarios under which status code of 500 is returned with an error message –
HTTPS Code Response Type Meaning Response Body
500 Internal Server Internal Server Error occurred {“responseStatus”: “ERROR”,
Error due to Bad Gateway or the “error”:
server failed to respond with a { “code”:”INTERNAL_SERVER_ERROR
valid json response. ”, “description”: “Something went
wrong” }
}
Callbacks:
Successful callback
{
"status": "200",
"is_retryable”: false,
"message": "success",
"data":
{
"account_id": "PARTNERID1000001",
"async_id": "PTM20210607123456789abcdef",
"abfl_application_id": "B2B000000000001",
"loan_amount": "10000",
"roi": "NA",
"tenure": "12",
"ccc_id": "123456",
"risk_flag": "LOW",
"pep_flag": "FALSE"
}
}
Call Back Response Table
Parameter Name Value
status Status code
is_retryable true/false
message Success / actual error
account_id Partners Unique application ID
async_id ABFL internal async ID
abfl_application_id ABFL internal application ID
loan_amount Actual loan amount
Roi Actual ROI
tenure tenure
ccc_id ABFL Unique customer ID which will be utilized
for other APIs
risk_flag LOW
pep_flag FALSE
Rejected callback.
{
"status": "412",
"is_retryable":false,
"message": "Rejected in ELMS API",
"data": {
"account_id": " PARTNERID1000001",
"async_id": "PTM20210607123456789abcdef",
}
}
Got unexpected response from Bureau. We will process this request separately.
{
"status": "202",
"is_retryable”: false,
"message": "Errors encountered with Bureau -Resolution WIP. Next update within 72 hours.",
"data": {
"account_id": " PARTNERID1000001",
"async_id": "PTM20210607123456789abcdef",
}
}
Validation Error response from Bureau
{
"status": "400",
"is_retryable”: true,
"message": "invalid request",
"data": {
"account_id": "PARTNERID1000001",
"async_id": "PTM20210607123456789abcdef",
}
}
Max Retry Exceeded:
{
"status": "508",
"is_retryable”: true,
"message": "Max retry limit for unscr API exhausted",
"data": {
"account_id": " PARTNERID1000001",
"async_id": "PTM20210607123456789abcdef",
}
}
