Create Leads
API endpoint
POST /v1/leads/bulks-direct
Refer the comment //Mandatory means the property is required
📌 API
sample data with reference of master list mapping
Request Mapping
{
"leads": [
{
"leadType": "Company", (List Id : 27 eg : Company)
"title": "Mr", (List Id : 50 eg : Mr)
"gender": "Male", (List Id : 52 eg: Male)
"nationality": "Saudi Arabian", (List Id : 51 eg : Saudi Arabian)
"firstName": "Abdullah", (user input eg : Abdullah)
"middleName": "Mobarak", (user input eg : Mobarak)
"lastName": "Careem", (user input eg : Careem)
"companyName": "string", (user input eg : any text)
"companyIndustryType": "Bank", (List Id : 39 eg : Bank)
"contactName": "Abdullah", (user input eg : Abdullah)
"dateOfBirth": "2025-08-17", (yyyy-MM-dd eg : 2025-08-17)
"occupation": "Civil Engineer", (List Id 53 eg : Civil Engineer)
"customerCountry": "Saudi Arabia", (List Id : 56 eg : Saudi Arabia)
"customerRegion": "Eastern Province", (List Id : 100 eg : Eastern Province)
"customerCity": "Dammam", (List Id : 101 eg : Dammam)
"address1": "Building 7, King Fahad Road", (user input eg : Building 7, King Fahad Road)
"address2": "Khobar", (user input eg : Khobar)
"phoneCode": "00966", (List Id : 62 eg: 00966)
"phoneNumber": "555555555", (user input eg : 5xxxxxxxx)
"email": "string", (user input eg : email)
"monthlyIncome": "0-5000 SAR", (List Id : 78 eg : 0-5000 SAR)
"preferredLanguage": "English", (List Id : 54 eg : English)
"preferredContactType": "Phone Call", (List Id : 55 eg : Phone Call)
"company": "JTC", (List Id : 0 eg : JTC)
"brand": "Kia", (List Id : 2 eg : Kia)
"businessArea": "Sales", (List Id : 3 eg : Sales)
"leadDate": "2025-08-17", (yyyy-MM-dd eg : 2025-08-17)
"interest": "Vehicle Inquiry", (List Id : 74 eg : Vehicle Inquiry)
"source": "Showroom", (List Id : 70 eg : Showroom)
"subSource": "Walk-in", (List Id : 71 eg : Walk-in)
"leadName": "Example Holdings", (user input eg : Example Holdings)
"leadReference": "string", (user input eg : any text)
"leadNote": "string", (user input eg : any text)
"vehicleType": "New", (List Id : 79 eg : New)
"vehicles": [
{
"modelFamily": "Rio", (List Id : 63 eg : Rio)
"modelYear": 2025, (List Id : 64 eg : 2025)
"modelMemo": "string", (user input eg : any text)
"modelPreferences": "string", (user input eg : any text)
"totalQty": 1 (minimum 1 & maximum 1000)
}
],
"purchasePlan": "Immediate", (List Id :59 eg : Immediate)
"paymentMode": "Cash", (List Id : 60 eg : Cash)
"currency": "SAR", (List Id : 61 eg : SAR)
"priority": "Hot", (List Id : 75 eg : Hot)
"testDriveRequired": true, (boolean eg : true)
"acceptNewsLetter": true, (boolean eg : true)
"acceptMarketing": true, (boolean eg : true)
"acceptPrivatePolicy": true, (boolean eg : true)
}
],
"isProcessed": 1
}
Request Body
Below are the possible values for creating lead and properties will be mandatory or optionals based on business conditions and type of the leads
Note
Minimum 1 Lead and Maximum 20 leads per request will be allowed and for each lead minimum one vehicle details and maximum 5 vehicle details will be allowed.
Lead Type : Company (Sample Json)
{
"leads": [ // Minimum 1 & Maximum 20
{
"leadType": "Company", // Mandatory
"contactName": "", // Mandatory
"companyName": "", // Mandatory
"companyIndustryType": "Bank", // Mandatory
"dateOfBirth": yyyy-MM-dd,
"occupation": "string",
"customerCountry": "Saudi Arabia", // Mandatory
"customerRegion": "Riyadh", // Mandatory
"customerCity": "Afif", // Mandatory
"address1": "string",
"address2": "string",
"phoneCode": "00966", // Mandatory
"phoneNumber": "", // Mandatory
"email": "",
"monthlyIncome": "string",
"preferredLanguage": "Arabic", // Mandatory
"preferredContactType": "email",
"company": "JTC", // Mandatory
"brand": "KIA", // Mandatory
"businessArea": "Sales", // Mandatory
"branch": "string",
"leadDate": "yyyy-MM-dd",
"interest": "Price Quote", // Mandatory
"source": "Direct Contact", // Mandatory
"subSource": "Email", // Mandatory
"leadName": "", // Mandatory
"leadReference": "",
"leadNote": "",
"vehicleType": "New",
"vehicles": [ // Minimum 1 & Maximum 5 // Mandatory
{
"modelFamily": "RIO", // Mandatory
"modelYear": "2024",
"modelMemo": "",
"modelPreferences": "",
"totalQty": 1 // Mandatory
}
],
"purchasePlan": "Within 30 Days",
"paymentMode": "Credit",
"currency": "SAR",
"priority": "Warm", // Mandatory
"testDriveRequired": true, // Mandatory
"acceptNewsLetter": true, // Mandatory
"acceptMarketing": true, // Mandatory
"acceptPrivatePolicy": true // Mandatory
}
],
"isProcessed": 1
}
Lead Type : Individual (Sample Json)
{
"leads": [ // Minimum 1 & Maximum 20
{
"leadType": "Individual", // Mandatory
"title": "Mr",
"gender": "Male",
"nationality": "Saudi Arabian",
"firstName": "", // Mandatory
"middleName": "",
"lastName": "",
"contactName": "",
"companyName": "",
"companyIndustryType": "",
"dateOfBirth": "yyyy-MM-dd",
"occupation": "",
"customerCountry": "Saudi Arabia", // Mandatory
"customerRegion": "Riyadh", // Mandatory
"customerCity": "Afif", // Mandatory
"address1": "",
"address2": "",
"phoneCode": "00966", // Mandatory
"phoneNumber": "", // Mandatory
"email": "",
"monthlyIncome": "5000-10000 SAR",
"preferredLanguage": "Arabic", // Mandatory
"preferredContactType": "Email",
"company": "JTC", // Mandatory
"brand": "KIA", // Mandatory
"businessArea": "Sales", // Mandatory
"branch": "string",
"leadDate": "yyyy-MM-dd",
"interest": "Price Quote", // Mandatory
"source": "Direct Contact", // Mandatory
"subSource": "Email", // Mandatory
"leadName": "", // Mandatory
"leadReference": "",
"leadNote": "",
"vehicleType": "New",
"vehicles": [ // Minimum 1 & Maximum 5 // Mandatory
{
"modelFamily": "RIO", // Mandatory
"modelYear": "2024",
"modelMemo": "",
"modelPreferences": "",
"totalQty": 1 // Mandatory
}
],
"purchasePlan": "Within 30 Days",
"paymentMode": "Credit",
"currency": "SAR",
"priority": "Warm", // Mandatory
"testDriveRequired": true, // Mandatory
"acceptNewsLetter": true, // Mandatory
"acceptMarketing": true, // Mandatory
"acceptPrivatePolicy": true // Mandatory
}
],
"isProcessed": 1
}
Response
{
"leads": [
{
"leadId": 1, // Incremental ID
"errorList": null
...
},
{
"leadId": 2, // Incremental ID
"errorList": null
...
}
],
"createdDate": "2025-09-30T09:23:03.683",
"createdBy": 4,
"totalRecords": 10,
"errorRecords": 0,
"isProcessed": 4 // Processed Status
}
Notes
errorRecords states the error count
leads states list of leads which are sent against this Id
`leadId` created in DMS
`errorList` explains the errors that is occurring against the `leadId`
Warning
"Maximum 20 leads are allowed"
* leadType: string
GET /v1/leads/list?listId={CUSTOMER_TYPE}
Mandatory Fields for Company Lead Type
When leadType value is Individual, the following fields are mandatory
firstName
When leadType value is Company, the following fields will be mandatory:
companyIndustryTypecontactNamecompanyName
companyIndustryType: string
GET /v1/leads/list?listId={CUSTOMER_INDUSTRY_TYPE}
contactName: string
companyName: string
title: string
GET /v1/leads/list?listId={TITLE}
nationality: string
/v1/leads/list?listId={NATIONALITY}
gender: string
GET /v1/leads/list?listId={GENDER}
firstName: string
lastName: string
middleName: string
dateOfBirth: yyyy-MM-dd
occupation: string
* customerCountry: string
GET /v1/leads/list?listId={COUNTRY}
* customerRegion: string
GET /v1/leads/list?listId={REGION}&parentId={customerCountry.value}
* customerCity: string
GET /v1/leads/list?listId={CITY}&parentId={customerRegion.value}
address1: string
address2: string
* phoneCode: string
GET /v1/leads/list?listId={PHONE_CODE}
phoneNumber: string
phoneNumber length should be 9 characters
email: string
monthlyIncome: string
GET /v1/leads/list?listId={LEAD_MONTHLY_INCOME}
* preferredLanguage: string
GET /v1/leads/list?listId={LANGUAGE}
preferredContactType: string
GET /v1/leads/list?listId={CONTACT_TYPE}
company: string
* ou: string
GET /v1/leads/list?listId={OU_TYPE}
* businessArea: string
GET /v1/leads/list?listId={BUSINESS_AREA}&parentId={ou_type.value}
* leadDate: string
* leadInterest: string
GET /v1/leads/list?listId={LEAD_INTEREST}
* source: string
GET /v1/leads/list?listId={LEAD_SOURCE}
* subSource: string
GET /v1/leads/list?listId={LEAD_SUB_SOURCE}&parentId={lead_source.value}
* leadName: string
leadReference: string
leadNote: string
vehicleType: string
GET /v1/leads/list?listId={VEHICLE_TYPE}
vehicles: array
Info
modelFamily: string
GET /v1/leads/list?listId={MODEL_FAMILY}&parentId={ou_type.value}
modelYear: string
GET /v1/leads/list?listId={MODEL_YEAR}
modelMemo: string
modelPreferences: string
totalQty: string
purchasePlan: string
GET /v1/leads/list?listId={PURCHASE_PLAN}
paymentMode: string
GET /v1/leads/list?listId={PAYMENT_MODE}
currency: string
GET /v1/leads/list?listId={CURRENCY}
* priority: string
GET /v1/leads/list?listId={LEAD_PRIORITY}