Updating Lead Outcomes

Use this guide only when you need to update a lead’s outcome or status (e.g. move a lead from new to contacted or lost).

To update other lead attributes — name, email, phone, message, date of birth, tags, vehicle, address, and custom fields — use the dedicated lead update endpoint instead. See Creating and Updating Leads.

Lead status is managed on the lead cluster, not on individual leads. When you create a lead, the response includes lead_cluster_id — use that ID here.

Endpoint

PUT https://dashboard.dealerstudio.com.au/api/v1/dealerships/{dealership_slug or dealership_id}/lead_clusters/{lead_cluster_id}

When leads are sent to you from Dealer Studio, we include dealership_slug, dealership_id, and lead_cluster_id.

Looking up valid status values

Status options are dealership-specific. Fetch them before updating:

GET /api/v1/dealerships/{dealership_slug}/lead_status_options

OpenAPI reference: List lead status options.

Use the id from the response as lead_status_option_id below.

Payload

Preferred — lead_status_option_id

{
  "lead_cluster": {
    "lead_status_option_id": 762
  }
}

Legacy — lead_state

Pass the status name (must match a name value from the lookup endpoint for that dealership’s pipeline):

{
  "lead_cluster": {
    "lead_state": "contacted"
  }
}

Default status names at most dealerships are new, contacted, converted, delivered, lost, and spam, but dealers can rename or add custom statuses. Always use the lookup endpoint rather than hard-coding values.

Headers

{
  "Authorization": "Bearer 1234567890",
  "Accept": "application/json",
  "Content-Type": "application/json"
}