Lead APIs Documentation
All of the homefirst APIs are REST API and if you’ve worked on RESTFul APIs before, then it’ll
be a piece of cake to consume them. All of these are uniquely identified by a unique URL and
follow standard HTTP GET and POST calls. Both Request and Response use JSON to
communicate data back and forth.
HTTP Methods
GET - Used to read or retrieve data.
POST - Uses to create or update data.
In some cases, we’ll be using both methods a little differently.
Base URLs
Sandbox: [Link]
Production: [Link]
Authentication
All the APIs will be authenticated using Basic Authentication with a Base64 hash of the Client
ID and Client Secret and additionally an Org ID - which will be provided to you separately. This
information will be passed in the Headers to authenticate yourself with the Homefirst server.
After successful authentication, you’ll receive a sessionPasscode, which will be valid for 1
Hour from the moment you generated it. This passcode will be used to access further APIs
along with the previous headers.
IP Whitelisting
In order to access these APIs, you’ll have to provide us a Public Static IP of your organization,
that we’ll whitelist at our end.
Copyright © 2020 Homefirst Finance Company India Ltd. All rights reserved.
Response codes
200 Success.
201 Error. Description of the error will be there in the JSON Response body with
status, message, error and action.
401 Unauthorized access / Invalid credentials.
500 Internal server error.
API Description
1. Authenticate Client
This API is used for retrieving a sessionPasscode to get access to all the resources.
Endpoint:
GET: {BASE_URL}/V1/client/authenticateClient
Headers params:
Authorization : “Basic Base64(YourClientID:YourClientSecret)”
orgId: “YOUR_ORG_ID”
Response:
{
"sessionPasscode": "AqBnix6X*************K+veezK02nhJt4=",
"validUpto": "2020-09-30 13:50:10"
}
Store the sessionPasscode received and use it to make further API calls. This passcode
is valid for 1 hour from the moment you create it.
Note: DO NOT hit this API to generate a new passcode every time. Create a new
passcode only if the existing passcode has expired. You’ll get 401 response code
whenever the passcode has expired while using any other API (eg. createLead), then
only hit authenticateClient API to get a new one.
Copyright © 2020 Homefirst Finance Company India Ltd. All rights reserved.
2. Create Lead
This API is used to create a new Lead.
Endpoint:
POST: {BASE_URL}/V1/client/createLead
Headers params:
Authorization : “Basic Base64(YourClientID:YourClientSecret)”
orgId: “YOUR_ORG_ID”
sessionPasscode: “SESSION_PASSCODE_RECEIVED”
Request:
{
"firstName": "John",
"lastName": "Doe",
"mobileNumber": "7715857966",
"emailId": "john@[Link]",
"loanAmount": 125000,
"dob" : "1990-07-01",
"hasConsented": true,
"address": {
"street": "1 Madonna, Mith Chowki, Malad (W)",
"city": "Mumbai",
"state": "Maharashtra",
"country": "India",
"postalCode": "400064"
}
}
Response:
{
"message": "Lead created.",
"leadId": "26a13110-44b5-415a-a602-b04b073776f4"
}
Store the leadId received for your future reference.
Copyright © 2020 Homefirst Finance Company India Ltd. All rights reserved.
All possible Lead parameters
Param Description Size (Max length) Mandatory?
salutation Type: String 8 No
Value: Mr. / Ms. / Mrs. / Dr. / Prof.
firstName Type: String 64 Yes
middleName Type: String 32 No
lastName Type: String 45 Yes
hasConsented Type : Boolean - Yes
countryCode Type: String 8 No
Value: +91
mobileNumber Type: String 10 Yes
emailId Type: String 128 No
loanType Type: String 64 No
Value: Refer appendix section
loanAmount Type: Double (Rs) - Yes
dob Type: String 10 No
Value: yyyy-MM-dd
propertyValue Type: Double (Rs) - No
partnerReferenceId Type: String (UNIQUE) 128 No
Value: This is a unique identifier of
the lead in your system for your
reference. It’s an optional field. If
passed, then it has to be unique for
each lead.
monthlyIncome Type: Double (Rs) - No
documentType Type: String 24 No
Value: Aadhaar/PAN
documentId Type: String PAN : 10 No. Yes, if
Aadhaar: 12 documentType
is set.
address Type: JSON - No
Desc: Current residential address
street Type: String 128 No
Copyright © 2020 Homefirst Finance Company India Ltd. All rights reserved.
city Type: String 45 No
Value: Standar City name
state Type: String 45 No
Value: Refer appendix section
postalCode Type: String 8 No
propertyAddress Type: JSON - No
Desc: Property address / location
street Type: String 128 No
city Type: String 45 No
Value: Standar City name
state Type: String 45 No
Value: Refer appendix section
postalCode Type: String 8 No
comment Type: String 512 No
remark Type: String 512 No
source Type: String 32 No
medium Type: String 32 No
campaign Type: String 32 No
employmentType Type: String - No
Values: Salaried / Self Employed
salariedType Type: String - No
Desc : Pass this value if
employmentType is Salaried
Values: Bank / Cash
propertyIdentified Type: Boolean - No
Values: true / false
gender Type: String - No
Values: Male / Female
tenure Type: Integer - No
Value: 1 - 25 (Years)
appointmentDatetime Type : String 19 No
Desc : Datetime of the Appointment
with the customer.
Format : yyyy-MM-dd HH:mm:ss
Time Zone : IST
companyName Type: String 128 No
alternateContactNumber Type: String 16 No
Copyright © 2020 Homefirst Finance Company India Ltd. All rights reserved.
Appendix
Loan Types
Commercial Property Loan Plot Loan (BT) + SECO
HL-BT + Renovation Loan Shop Loan - BT
HL-BT + SECO Construction Finance Product
Home Loan Shop Loan BT + Top Up
Home Loan (BT) LTV Enhancement
Home Loan (BT) + Top Up Non Credit Insurance
Home Loan (Resale) Own Plot + HL (SeCo)
LAP-BT Plot Loan
LAP-BT + Renovation Loan Plot Loan + HL (SeCo)
LAP-BT + SECO Shop Loan (Resale)
LAP-BT + Top-Up Top Up Loan
Loan Against Property (LAP) LAP + Renovation
Loan Against Property against commercial LAP + SECO
property
Loan for Repair / Renovation / Extension
Copyright © 2020 Homefirst Finance Company India Ltd. All rights reserved.
States
Andaman and Nicobar Islands Manipur
Andhra Pradesh Madhya Pradesh
Arunachal Pradesh Mizoram
Assam Nagaland
Bihar Odisha
Chandigarh Punjab
Chhattisgarh Puducherry
Daman and Diu Rajasthan
Delhi Sikkim
Dadra and Nagar Haveli Telangana
Goa Tamil Nadu
Gujarat Tripura
Himachal Pradesh Uttar Pradesh
Haryana Uttarakhand
Jharkhand West Bengal
Jammu and Kashmir Meghalaya
Karnataka Lakshadweep
Copyright © 2020 Homefirst Finance Company India Ltd. All rights reserved.
Kerala Maharashtra
Copyright © 2020 Homefirst Finance Company India Ltd. All rights reserved.