Skip to content
Dealer Studio API Docs

Create Lead

POST
/api/v1/leads

This endpoint allows to you to create a new lead into Dealer Studio.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
object
lead
required
object
name

Customer Full Name

string
email
required

Customer Email

string
phone
required

Customer Phone Number

string
message

Customer Message

string
dealership_id
required

Dealership ID (Identifier from Dealer Studio)

integer
dealership_slug

Dealership Slug (Identifier from Dealer Studio)

string
category
required

Lead category, must be from the list of categories below

string
Allowed values: New Vehicle Enquiry Used Vehicle Enquiry Test Drive Booking Special Offer Enquiry Fleet Enquiry Finance Enquiry Insurance Enquiry Subscription Enquiry Team Member Enquiry Vehicle Reservation Online Purchase Brochure Download Document Request Trade-in Enquiry Sell My Car Enquiry Service Booking Service Enquiry Parts Enquiry Service Retention Loan Car Booking General Enquiry Survey Competition Enquiry Phone Call Event Enquiry
source
required
string
Allowed values: Walk In Website Event Facebook Facebook Marketplace Chatbot Chatbot - External QR Code Carsales Autotrader Phone Call SMS Connect Drive Car Expert Manufacturer Autograb Ford Mobile App Only Cars Google Ads Google Referral Brisbane Cars Tweed Cars Repeat IApprise CBA Bulk SMS Campaign Retention Carbee
marketing_source
string
Allowed values: Facebook Adwords Organic Unknown QR Code Email SMS GMB Carsales Instagram Popup Linkedin CRM Messenger Audience Network TikTok YouTube
website_id
integer
website_slug
string
page_id

ID of the page where the lead was submitted from

integer
stocknum

If supplied, will match the lead against a vehicle with matching stocknum (if exists)

string
provider

Lead supplier name eg. “Carsales”

string
provider_id
string
certified
boolean
golden

Mark the lead cluster as golden (high priority lead)

boolean
location_id
integer
send_customer_email
boolean
car_id

If supplied, will match the lead against the relevant car. Car ID as supplied by Dealer Studio

integer
model_id

ID of the model (only relevent for new vehicle enquiries)

integer
team_member_id

Only for Team Member Enquiry leads

integer
user_email

Email of User if existed in DS used to associate the Lead

string
lead_state
string
sms_verified

Mark the contact as sms verified

boolean
model_variant_id

ID of the model variant (only relevent for new vehicle enquiries)

integer
colour_id

ID of the colour (only relevent for new vehicle enquiries)

integer
tags
Array<string>
opt_in_to_marketing
boolean
delay_customer_email_minutes
integer
delay_dealership_notification_minutes
integer
disable_strict_validation

If sent as true, then it skips emails AND phone validation

boolean
time_on_site_seconds

Time in seconds the customer spent on site before submitting

integer
nullable
time_to_submit_seconds

Time in seconds from form load to form submit

integer
nullable
lead_files_attributes

Object of attached files with their types for the lead

Array<object>
object
file_type
string
Allowed values: resume cover_letter other
file

The attached file for the lead

string format: binary
payment_attributes
object
amount
number format: float
car_id
integer
payment_processor_id
integer
external_transaction_id
string
address_attributes
object
street
string
city
string
state
string
state_long
string
postcode
integer
country
string
fields

Additional custom fields for the lead. For Document Request leads, include document_type (car_analysis, ppsr, equifax)

object
key
additional properties
any
Example
{
  "document_type": "ppsr",
  "custom_field": "value"
}
charge_breakdown

Charge breakdown hash containing charge details. Must include either total, charges, or both.

object
total

Total charge amount

object
amount
required

The total charge amount

number
key
additional properties
any
charges

Array of individual charge items

Array<object>
object
name
required

The name of the charge

string
amount
required

The charge amount

number
key
additional properties
any
Example
{
  "total": {
    "amount": 50
  },
  "charges": [
    {
      "name": "Luxury Car Tax",
      "amount": 1234
    },
    {
      "name": "Delivery Fee",
      "amount": 500
    }
  ]
}
Example
{
  "lead": {
    "name": "Test Lead",
    "last_name": "Test",
    "email": "test@test.com",
    "phone": "041000000",
    "message": "some notes",
    "dealership_slug": "test-dealer",
    "category": "New Vehicle Enquiry",
    "source": "Website",
    "website_slug": "example-website",
    "page_id": 123,
    "location_id": 12345,
    "user_email": "test@example.com",
    "lead_state": "new",
    "send_customer_email": false,
    "customer_address": "123 Fake Street",
    "stocknum": "3210",
    "provider": "Provider A",
    "provider_id": "1234",
    "dob": "01/01/1980",
    "tags": [
      "tag1"
    ],
    "address_attributes": {
      "street": "123 Fake Street",
      "city": "Melbourne",
      "state": "VIC",
      "state_long": "Victoria",
      "postcode": 3000,
      "country": "Australia"
    }
  }
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Create new lead

401

Section titled “401 ”

Unauthorised with correct bearer and dealership but invalid permissions