Lead Cluster Webhook

A lead cluster refers to a group of leads matched based on key customer information such as phone numbers or emails. The webhook exports lead cluster details when created or updated in Dealer Studio to external systems. The webhook sends it’s details and its associated leads details, updates, assignments, and status changes, to the external system associated to the endpoint configured.

Authorization: Token is OPTIONAL and can be discarded in the request if the Webhook Url doesn’t require authorization

POST webhook_api_url

The webhook_api_url parameter indicates the target system’s URL for lead export. The webhook_api_token is transmitted as a Bearer token in the authorization header.

Headers

Header Name	Value / Format	Notes
`Content-Type`	`application/json`	Payload is sent as JSON.
`Accept`	`application/json`	Response expected in JSON format.
`Authorization (OPTIONAL)`	Authorization / X-Authorization	Supported Methods: API KEY: Header `X-Authorization: <token>` Bearer Token: Header `Authorization: Bearer <token>`

Response

Field	Value Required?	Description
Id	Yes	ID of Lead Cluster in Dealer Studio
dealership_id	Yes	ID of Dealer associated with Lead Cluster in Dealer Studio
provider	Yes	provider. default as Dealer Studio
status	Yes	Status of Lead Cluster (from Status Options shown below)
contact	Yes	Contact Details of Lead Cluster as shown below
approver	Yes	approve details of lead cluster as below. this is the person who approved the status changes of lead Cluster
assigned_salesperson	Yes	assigned sales person details of lead cluster as below
created	Yes	Created_at timestamp of Lead Cluster
modified	Yes	updated_at timestamp of Lead Cluster
first_lead_created_at	Yes	Created time of the first lead of Lead Cluster
last_lead_created_at	Yes	created time of the last lead of Lead Cluster
leads	Yes	Array of leads associated with lead Cluster in Dealer Studio
lead_events	Yes	Lead events associated to the lead Cluster recorded in DS

Contact

Field	Value Required?	Description
business_name	No	Lead’ Cluster’s customer business name /title
first_name	Yes	Lead Cluster customer first name
last_name	Yes	Lead Cluster customer last name
email	Yes	Lead Cluster customer email
postcode	No	Lead Cluster customer postcode field
mobile_phone	Yes	Lead Cluster customer Phone
dob	No	Lead Cluster customer Date of Birth if provided else returned nil

Approver

Field	Value Required?	Description
id	Yes	Approver Id of Lead Cluster in DS
name	Yes	name of approver approved lead Cluster status change in DS

Assigned SalesPerson

Field	Value Required?	Description
id	Yes	Assigned User Id of Lead Cluster in DS
name	Yes	name of Assigned User of lead Cluster in DS

Lead Attributes

Field	Value Required?	Description
id	Yes	Lead ID in Dealer Studio
website_url	No	Lead’s website url
source	Yes	Source from the list below
category	Yes	Category from the list below
location	Yes	Location details from where the Lead submitted — Mostly within the dealer’s location that exist in DS. object details explained below
prospect	Yes	Lead Customer details as object from below Prospect fields
subscription	Yes	Lead’s subscription object fields below
comments	No	Lead’s message
created	Yes	Lead created_at
modified	Yes	Lead updated_at
booking_date	No	Appointment date set for Test Drive Bookings or Service Bookings with date as string. For other enquiries it will not be part of payload.
booking_time	No	Appointment time set for Test Drive Bookings or Service Bookings with time as string. For other enquiries it will not be part of payload.
item	Yes	Lead vehicle details as object with below Item fields
additional_details	No	This holds any fields that are not mapped to any existing key in the payload get mapped here
trade_in_data	No	This includes lead’s field values when Enquiry Type is Trade-In Enquiry or Sell My Car Enquiry. For other enquiries this field is not mapped.
offer_data	No	This includes lead’s field values when Enquiry Type is Special Offer Enquiry. For other enquiries this field is not mapped.
budget	No	Lead’s vehicle budget if Category is Finance Enquiry
purchase_price	No	Lead’s Purchase Price budget if Category is Finance Enquiry

Location

Field	Value Required?	Description
street	Yes	Street from Location details of Lead (one of the Dealership Locations)
suburb	No	Suburb of the Location details. It is OPTIONAL
city	Yes	City from Location details of Lead (one of the Dealership Locations)
state	Yes	State from Location details of Lead (one of the Dealership Locations)
postcode	Yes	Postcode from Location details of Lead (one of the Dealership Locations)

Prospect

Field	Value Required?	Description
name	Yes	Lead’s first name
last_name	Yes	Lead’s last name
email	Yes	Lead’s customer email
postcode	No	Lead postcode field
home_phone	No	Lead’s Phone
mobile_phone	Yes	Lead’s Mobile Phone
address	No	Address details of Lead (if provided on lead creation). it is returned nil if no address mapped for Lead
licence_type	No	Lead’s licence_type if Category is Finance Enquiry, else returned nil
driver_licence_number	No	Lead’s driver licence if Category is Finance Enquiry else returned nil
employment_type	No	Lead’s Employment Type if Category is Finance Enquiry else returned nil
dob	No	Lead’s Date of Birth if provided else returned nil
residency_status	Yes	Lead’s residency status if provided else returned nil

Address

Field	Value Required?	Description
street	Yes	Street from Location details of Lead (one of the Dealership Locations)
city	Yes	City from Location details of Lead (one of the Dealership Locations)
state	Yes	State from Location details of Lead (one of the Dealership Locations)
postcode	Yes	Postcode from Location details of Lead (one of the Dealership Locations)

Subscription

Field	Value Required?	Description
newsletter	Yes	Lead’s opt_in Default: true

Item

Field	Value Required?	Description
type	Yes	’Car’
car_type	Yes	Car’s car type from below list
id	No	Lead’s car Id
vin	No	Car’s Vin of Lead
status	No	Status of Vehicle attached to Lead. It will be any of these values: In Stock, Sold, Coming soon. null if no vehicle attached
colour	No	Car’s colour
body_type	No	Car’s Body Type
redbook_code	No	Car’s redbook code
build_date	No	Car’s build date
transmission	No	Car’s transmission either Automatic or Manual
interior_colour	No	Car’s interior colour
stock_number	No	Lead’s car stock_num
deposit	No	Lead’s Deposit amount if Category is Finance Enquiry
make	No	Car make (manufacturer name) value of the lead
model	No	Car model of the lead
badge	No	Car badge of the lead
year	No	Car year value of lead
price	No	Car price
rego	No	Car rego
engine_size	No	Engine Size of Car
km	No	Car kms
comments	No	Dealer comments of Car
series	No	Series of Car
url	No	Car’s url or Lead url
spin_code	No	Spin code of car
third_party_integrations	No	Car’s third party integrations existed on DS

Trade-In Data

Field	Value Required?	Description
rego	Yes	rego of the detail submitted through form on website
kms	Yes	Kms on Lead Fields
state	Yes	State selected on Trade-In form
title	Yes	Combination of Year, make, model, badge, series
year	Yes	Year of Car from Lead Fields
make	Yes	Make of Car from Lead Fields
model	Yes	Model of Car from Lead Fields
badge	Yes	Badge of Car from Lead Fields
series	Yes	Series of Car from Lead Fields
retail_price	Yes	Retail price after valuation of the car
trade_price	Yes	Trading price of the car after valuation
price_adjustment	Yes	Price adjustment made after valuation
offer_price	Yes	Offered price for Lead Fields car
offer_accepted	Yes	Flag to determine whether the user accepted the offer or not. Values are true or false as boolean

Offer Data

Field	Value Required?	Description
manufacturer	No	Manufacturer of Car
offer_name	No	Offer title

Lead Events Attributes

Field	Value Required?	Description
id	Yes	ID of the lead event in DS
event_type	Yes	Type of the event associated. Any one of these: [‘email’, ‘phone’, ‘sms’, ‘test_drive’, ‘note’]
description	Yes	description of the event
created_at	Yes	CreatedAt timestamp of the event in DS system
updated_at	Yes	UpdatedAt timestamp of the event in DS system
external_service	No	Service from which the lead event is created.
deleted_at	No	deleted_at if in case the lead event is deleted at DS
followup_reason	No	reason for follow up of the lead event with lead
followup_datetime	No	Time of the followup of the event
followup_status	Yes	Status of the lead event. It will be any one of the below: [‘pending’, ‘completed’]
followup_completed_at	No	Follow up Completedat timestamp of the event
user_name	No	User created the Lead event

Example Payload

{
  "id": 112233,
  "dealership_id": 121,
  "provider": "Dealer Studio",
  "status": "New",
  "contact": {
    "business_name": null,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@hotmail.com",
    "dob": null,
    "postcode": 4567,
    "mobile_phone": "+61411111111"
  },
  "approver": {
    "id": 12,
    "name": "Approver"
  },
  "assigned_salesperson": {
    "id": 112,
    "name": "Salesperson"
  },
  "created": "2025-03-13T12:08:32.458Z",
  "modified": "2025-03-13T12:22:11.904Z",
  "pipeline": {
    "id": 123,
    "name": "Sales"
  },
  "first_lead_created_at": "2025-03-13T12:21:08.000Z",
  "last_lead_created_at": "2025-03-13T12:21:08.000Z",
  "leads": [
    {
      "id": 1041902,
      "website_url": null,
      "source": "Carsales",
      "category": "Used Vehicle Enquiry",
      "location": {
        "street": "116 Eagle St",
        "city": "Eagle Farm",
        "state": "QLD",
        "postcode": 4009
      },
      "prospect": {
        "title": "Mr",
        "name": "SMS",
        "last_name": "Connect Prospect",
        "middle_name": null,
        "email": null,
        "postcode": 4009,
        "home_phone": null,
        "mobile_phone": "+61414632323",
        "address": null,
        "dob": null,
        "licence_type": "Full",
        "driver_licence_number": "123456789",
        "employment_type": "Full Time",
        "living_situation": "Owning",
        "residency_status": "Citizen"
      },
      "subscription": {
        "newsletter": false
      },
      "comments": "Thank you \nMy partner is looking for a new car , are you open over the weekend ?",
      "budget": "$60,000",
      "purchase_price": 60000.0,
      "created": "2025-03-13T12:22:11.235Z",
      "modified": "2025-03-13T12:22:11.235Z",
      "item": {
        "type": "Car",
        "car_type": "new",
        "id": 103108,
        "vin": "ASHJNBV436",
        "status": "In stock",
        "colour": "white",
        "body_type": "Ute",
        "stock_number": "aqlrny",
        "redbook_code": "REDH21321",
        "build_date": "2022-02-25",
        "transmission": "Automatic",
        "interior_color": "Red",
        "deposit": 2000.55,
        "make": "Haval",
        "model": "jolion",
        "badge": "gasda",
        "year": 2011,
        "rego": "123VEV",
        "price": 81475.0,
        "engine_size": "2.0L",
        "km": 17368.0,
        "series": "Cannon",
        "comments": "Great Car!!",
        "url": "https://www.tinthouse.com.au/cars/demo-2011-haval-jolion-aqlrny",
        "spin_code": "1725593452345_dsfd34faq324fer4r5r34dfst4gfvdrsger",
        "third_party_integrations": [
          {
            "service": "Autograb",
            "external_id": "abc123"
          }
        ]
      },
      "additional_details": {
        "more_details": "details"
      },
      "booking_date": "2025-03-13",
      "booking_time": "12:00PM",
      "trade_in_data": {
        "rego": "151VEV",
        "kms": 350000,
        "state": "QLD",
        "title": "2014 Mazda CX-5 Maxx KE Series Manual MY14",
        "year": 2014,
        "make": "Mazda",
        "model": "CX-5",
        "badge": "Maxx",
        "series": "KE Series",
        "retail_price": 8506,
        "trade_price": 5529,
        "price_adjustment": 0,
        "offer_price": 5529,
        "offer_accepted": true
      },
      "offer_data": {
        "manufacturer": "Manufacturer ABC",
        "offer_name": "Offer 1234"
      }
    }
  ],
  "lead_events": [
    {
      "id": 6,
      "event_type": "sms",
      "description": "Tried calling, but didnt answer!",
      "created_at": "2024-06-04T01:06:20.343Z",
      "updated_at": "2024-06-04T01:06:20.343Z",
      "external_service": "Impel",
      "deleted_at": null,
      "followup_reason": null,
      "followup_datetime": null,
      "followup_status": "completed",
      "followup_completed_at": "2024-06-04T03:06:20.343Z",
      "user_name": "John Don"
    }
  ]
}

Category Options

Category is required, and must be one of the following:

New Vehicle Enquiry
Used Vehicle Enquiry
Special Offer Enquiry
Test Drive Booking
Trade-in Enquiry
Sell My Car Enquiry
Fleet Enquiry
Service Booking
Service Enquiry
Parts Enquiry
General Enquiry
Finance Enquiry
Insurance Enquiry
Competition Enquiry
Survey
Subscription Enquiry
Team Member Enquiry

Source Options

Source is required and must be one of the following:

Website
Facebook
Facebook Marketplace
Chatbot
Chatbot — External
QR Code
Carsales
Autotrader
Walk In
Phone call

Status Options

Status is required and must be one of the following:

New
Contacted
Lost
Converted

There can be other status options set by dealer in Dealer Studio.

Item Type Options

Item Type is required and must be one of the following:

Car
Motorcycle
Boat
Caravan
Truck
Trailer
Bus
Machinery
Other