Leads

Capture enquiries, manage follow-up, associate vehicles, record messages, and send replies through MotorDesk communication channels.

The Lead Object

Generated from the OpenAPI schema. Always matches the live API.

Fields (31)

Attribute	Type	Required	Description	Example
`id`	integer	-	Lead id.	`4009`
`site`	integer	-	Site id, or 0 for none.	`0`
`channel`	string	-	Channel the lead came in on (e.g. api, website, email).	`website`
`reference`	integer	-	Lead reference number.	`10472`
`name`	string	-	The lead's name.	`Jane Doe`
`email`	string	-	The lead's email address.	`jane.doe@example.com`
`phone`	string	-	The lead's landline number.	`01612345678`
`mobile`	string	-	The lead's mobile number.	`07700900123`
`contact`	integer or null	-	Linked contact id, or null.	`110153`
`type`	array of string	-	Lead enquiry type(s), in snake_case (e.g. test_drive, part_exchange). See /reference/lead-types.	`["test_drive"]`
`status`	object	-	Primary workflow status.
`status.id`	integer	-	Status code (0-5).	`0`
`status.name`	enum	-	Status name.	`new`
`rating`	integer or null	-	AI buying-intent rating: 5 ready to transact, 4 specific vehicle and questions, 3 genuine interest, 2 vague or early, 1 not a buyer. Null when not rated. Never a spam score (see status junk).	`4`
`summary`	string or null	-	AI summary of where the conversation stands, at most 12 words, or null.	`Wants Saturday test drive of the Golf, asked for finance figures.`
`created`	integer	-	Unix timestamp the lead was created.	`1781303332`
`updated`	integer	-	Unix timestamp the lead was last updated.	`1781309000`
`session`	string	-	Visitor session reference (full view only).
`avatar`	string	-	Avatar reference (full view only).
`assign`	array of integer	-	Staff user ids the lead is assigned to (full view only).
`tag`	array of object	-	Applied lead tags ({ name, checked, colour, type }), full view only. Same shape as GET /leads/{id}/tags applied.
`stat`	boolean	-	Statistics flag: whether the lead counts toward reporting/KPIs (full view only).
`reopen`	string (date) or null	-	Date a closed lead will auto-reopen, or null (full view only).
`data`	object	-	Lead detail (source, message, subject, url, vehicle, appointment, junk) (full view only).
`ai`	object or null	-	The AI's latest read of the conversation, or null when it has not run (full view only).
`ai.intent`	string or null	-	Main aim, as one of the ids used by type (e.g. test_drive, finance, part_exchange, email for a general enquiry), or other.	`test_drive`
`ai.rating_reason`	string or null	-	Why the rating was given.
`ai.next_action`	string or null	-	Suggested next step for the dealer.
`ai.junk`	boolean	-	Whether the AI considered the latest message junk. Only high-confidence junk on an unanswered lead moves it to status junk.
`ai.junk_confidence`	enum or null	-
`ai.processed`	integer or null	-	Unix timestamp the AI last processed the lead.

Example object

{
    "id": 4009,
    "site": 0,
    "channel": "website",
    "reference": 10472,
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "phone": "01612345678",
    "mobile": "07700900123",
    "contact": 110153,
    "type": [
        "test_drive"
    ],
    "status": {
        "id": 0,
        "name": "new"
    },
    "rating": 4,
    "summary": "Wants Saturday test drive of the Golf, asked for finance figures.",
    "created": 1781303332,
    "updated": 1781309000,
    "session": "",
    "avatar": "",
    "assign": [
        0
    ],
    "tag": [
        {
            "name": "",
            "checked": false,
            "colour": "",
            "type": "default"
        }
    ],
    "stat": false,
    "reopen": "2026-01-01",
    "data": {},
    "ai": {
        "intent": "test_drive",
        "rating_reason": "",
        "next_action": "",
        "junk": false,
        "junk_confidence": "high",
        "processed": 0
    }
}

Endpoints

GET List Leads

GET /2.0/leads · scope leads:read

List leads with pagination and optional filters (status, channel, site, customer, created/updated range).

Parameters (18)

Parameter	In	Type	Required	Description	Example
`page`	query	integer	-	Page number, starting at 1 (offset pagination).
`per_page`	query	integer	-	Results per page (maximum 500).
`view`	query	enum	-	Response detail: "simple" for a compact object or "full" for the complete object.
`site`	query	integer	-	Filter by site id.
`status`	query	string	-	Filter by status, as the code or the name the lead reads back: 0 new, 1 new_message, 2 read, 3 replied, 4 closed, 5 junk.	`replied`
`channel`	query	string	-	Filter by channel.
`reference`	query	integer	-	Filter by reference.
`name`	query	string	-	Filter by name.
`email`	query	string	-	Filter by email. Supports wildcards (%) with the search:wildcard scope.
`phone`	query	string	-	Filter by phone.
`mobile`	query	string	-	Filter by mobile.
`contact`	query	integer	-	Filter by contact id.
`vehicle`	query	integer	-	Filter to leads associated with this vehicle id.
`rating_min`	query	integer	-	Only leads the AI rated at or above this buying intent (1-5). Unrated leads are excluded.	`4`
`created`	query	string	-	Unix timestamp exact match, or a two-element array [from, to] for a range. An empty bound is open-ended.
`updated`	query	string	-	Unix timestamp exact match, or a two-element array [from, to] for a range. An empty bound is open-ended.
`cursor`	query	string	-	Keyset pagination cursor from a previous response's meta.pagination.next_cursor. When supplied, page/total are not returned.
`fields`	query	string	-	Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.

Responses

Status	Description
`200` OK	Paginated leads

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": [
        {
            "id": 4009,
            "site": 0,
            "channel": "website",
            "reference": 10472,
            "name": "Jane Doe",
            "email": "jane.doe@example.com",
            "phone": "01612345678",
            "mobile": "07700900123",
            "contact": 110153,
            "type": [
                "test_drive"
            ],
            "status": {
                "id": 0,
                "name": "new"
            },
            "rating": 4,
            "summary": "Wants Saturday test drive of the Golf, asked for finance figures.",
            "created": 1781303332,
            "updated": 1781309000,
            "session": "",
            "avatar": "",
            "assign": [
                0
            ],
            "tag": [
                {
                    "name": "",
                    "checked": false,
                    "colour": "",
                    "type": "default"
                }
            ],
            "stat": false,
            "reopen": "2026-01-01",
            "data": {},
            "ai": {
                "intent": "test_drive",
                "rating_reason": "",
                "next_action": "",
                "junk": false,
                "junk_confidence": "high",
                "processed": 0
            }
        }
    ],
    "meta": {
        "pagination": {
            "page": 0,
            "per_page": 0,
            "total": 0,
            "total_pages": 0,
            "next_cursor": ""
        }
    }
}

POST Create Lead

POST /2.0/leads · scope leads:write

Create a lead.

Request body

Attribute	Type	Required	Description	Example
`site`	integer	-	Site id from /reference/sites; 0 for no site.	`0`
`channel`	string	-	Lead channel, e.g. api, website, email, sms. Defaults to api.	`api`
`channel_id`	string	-	External reference for the channel (e.g. a messaging thread id).
`name`	string	-	The lead's name.	`Jane Smith`
`email`	string	-	The lead's email address.	`jane.smith@example.com`
`phone`	string	-	Landline number in international format.	`441612345678`
`mobile`	string	-	Mobile number in international format.	`447700900123`
`contact`	integer	-	Existing contact id to link this lead to.	`77684`
`type`	string	-	Lead enquiry type(s) in snake_case (e.g. test_drive, part_exchange). See /reference/lead-types. Defaults to email (general enquiry).	`test_drive`
`data`	object	-	Free-form detail object stored against the lead.	`{}`
`status`	integer	-	Primary status code: 0 new, 1 new_message, 2 read, 3 replied, 4 closed, 5 junk. Prefer the named status field on /leads/{id}/status to change state after creation.	`0`
`tag`	array of string	-	Lead tags. Each item is a tag name string or { name, checked }; names must exist in the lead taxonomy (see GET /leads/{id}/tags or /reference/tags?resource=lead). Replaces the full set.	`[]`
`notify`	boolean	-	Whether to fire new-lead notifications on create. Defaults to true.	`true`
`vehicle`	integer	-	Create only: stock vehicle id the enquiry is about; the vehicle is associated with the new lead exactly as POST /leads/{id}/vehicles would. On an existing lead use that endpoint instead. Use this or vehicle_tag.	`85481`
`vehicle_tag`	string	-	Create only: vehicle tag the enquiry is about, as an alternative to vehicle.	`HbSDTp97`

{
    "site": 0,
    "channel": "api",
    "channel_id": "",
    "name": "Jane Smith",
    "email": "jane.smith@example.com",
    "phone": "441612345678",
    "mobile": "447700900123",
    "contact": 77684,
    "type": "test_drive",
    "data": {},
    "status": 0,
    "tag": [],
    "notify": true,
    "vehicle": 85481,
    "vehicle_tag": "HbSDTp97"
}

Responses

Status	Description
`201` Created	Lead created

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 4009,
        "site": 0,
        "channel": "website",
        "reference": 10472,
        "name": "Jane Doe",
        "email": "jane.doe@example.com",
        "phone": "01612345678",
        "mobile": "07700900123",
        "contact": 110153,
        "type": [
            "test_drive"
        ],
        "status": {
            "id": 0,
            "name": "new"
        },
        "rating": 4,
        "summary": "Wants Saturday test drive of the Golf, asked for finance figures.",
        "created": 1781303332,
        "updated": 1781309000,
        "session": "",
        "avatar": "",
        "assign": [
            0
        ],
        "tag": [
            {
                "name": "",
                "checked": false,
                "colour": "",
                "type": "default"
            }
        ],
        "stat": false,
        "reopen": "2026-01-01",
        "data": {},
        "ai": {
            "intent": "test_drive",
            "rating_reason": "",
            "next_action": "",
            "junk": false,
            "junk_confidence": "high",
            "processed": 0
        }
    }
}

GET Get Lead

GET /2.0/leads/{id} · scope leads:read

Retrieve a single lead by id.

Parameters (2)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.
`fields`	query	string	-	Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.

Responses

Status	Description
`200` OK	Lead

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 4009,
        "site": 0,
        "channel": "website",
        "reference": 10472,
        "name": "Jane Doe",
        "email": "jane.doe@example.com",
        "phone": "01612345678",
        "mobile": "07700900123",
        "contact": 110153,
        "type": [
            "test_drive"
        ],
        "status": {
            "id": 0,
            "name": "new"
        },
        "rating": 4,
        "summary": "Wants Saturday test drive of the Golf, asked for finance figures.",
        "created": 1781303332,
        "updated": 1781309000,
        "session": "",
        "avatar": "",
        "assign": [
            0
        ],
        "tag": [
            {
                "name": "",
                "checked": false,
                "colour": "",
                "type": "default"
            }
        ],
        "stat": false,
        "reopen": "2026-01-01",
        "data": {},
        "ai": {
            "intent": "test_drive",
            "rating_reason": "",
            "next_action": "",
            "junk": false,
            "junk_confidence": "high",
            "processed": 0
        }
    }
}

PATCH Update Lead

PATCH /2.0/leads/{id} · scope leads:write

Update a lead. Only the supplied fields are changed.

Parameters (1)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.

Request body

Attribute	Type	Required	Description	Example
`site`	integer	-	Site id from /reference/sites; 0 for no site.	`0`
`channel`	string	-	Lead channel, e.g. api, website, email, sms. Defaults to api.	`api`
`channel_id`	string	-	External reference for the channel (e.g. a messaging thread id).
`name`	string	-	The lead's name.	`Jane Smith`
`email`	string	-	The lead's email address.	`jane.smith@example.com`
`phone`	string	-	Landline number in international format.	`441612345678`
`mobile`	string	-	Mobile number in international format.	`447700900123`
`contact`	integer	-	Existing contact id to link this lead to.	`77684`
`type`	string	-	Lead enquiry type(s) in snake_case (e.g. test_drive, part_exchange). See /reference/lead-types. Defaults to email (general enquiry).	`test_drive`
`data`	object	-	Free-form detail object stored against the lead.	`{}`
`status`	integer	-	Primary status code: 0 new, 1 new_message, 2 read, 3 replied, 4 closed, 5 junk. Prefer the named status field on /leads/{id}/status to change state after creation.	`0`
`tag`	array of string	-	Lead tags. Each item is a tag name string or { name, checked }; names must exist in the lead taxonomy (see GET /leads/{id}/tags or /reference/tags?resource=lead). Replaces the full set.	`[]`
`notify`	boolean	-	Whether to fire new-lead notifications on create. Defaults to true.	`true`
`vehicle`	integer	-	Create only: stock vehicle id the enquiry is about; the vehicle is associated with the new lead exactly as POST /leads/{id}/vehicles would. On an existing lead use that endpoint instead. Use this or vehicle_tag.	`85481`
`vehicle_tag`	string	-	Create only: vehicle tag the enquiry is about, as an alternative to vehicle.	`HbSDTp97`

{
    "site": 0,
    "channel": "api",
    "channel_id": "",
    "name": "Jane Smith",
    "email": "jane.smith@example.com",
    "phone": "441612345678",
    "mobile": "447700900123",
    "contact": 77684,
    "type": "test_drive",
    "data": {},
    "status": 0,
    "tag": [],
    "notify": true,
    "vehicle": 85481,
    "vehicle_tag": "HbSDTp97"
}

Responses

Status	Description
`200` OK	Lead updated

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 4009,
        "site": 0,
        "channel": "website",
        "reference": 10472,
        "name": "Jane Doe",
        "email": "jane.doe@example.com",
        "phone": "01612345678",
        "mobile": "07700900123",
        "contact": 110153,
        "type": [
            "test_drive"
        ],
        "status": {
            "id": 0,
            "name": "new"
        },
        "rating": 4,
        "summary": "Wants Saturday test drive of the Golf, asked for finance figures.",
        "created": 1781303332,
        "updated": 1781309000,
        "session": "",
        "avatar": "",
        "assign": [
            0
        ],
        "tag": [
            {
                "name": "",
                "checked": false,
                "colour": "",
                "type": "default"
            }
        ],
        "stat": false,
        "reopen": "2026-01-01",
        "data": {},
        "ai": {
            "intent": "test_drive",
            "rating_reason": "",
            "next_action": "",
            "junk": false,
            "junk_confidence": "high",
            "processed": 0
        }
    }
}

DELETE Delete Lead

DELETE /2.0/leads/{id} · scope leads:delete

Delete a lead.

Parameters (1)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.

Responses

Status	Description
`200` OK	Lead deleted

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 0,
        "deleted": false
    }
}

Status

PATCH Update Lead Status

PATCH /2.0/leads/{id}/status · scope leads:write

Set lead state. status sets the primary workflow state (new, new_message, read, replied, closed, junk); junk and closed/reopen are conveniences over it; stat toggles the separate statistics flag. status cannot be combined with closed or junk.

Parameters (1)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.

Request body

Attribute	Type	Required	Description	Example
`status`	enum	-	Set the primary workflow status directly. new=unactioned lead, new_message=unread inbound message, read=acknowledged, replied=staff has replied, closed, junk. Overrides any current status (including junk).	`read`
`junk`	boolean	-	true marks the lead as junk (status junk); false clears junk and resets to new.	`false`
`closed`	boolean	-	true closes the lead (status closed); false reopens it (status new_message).	`true`
`reopen`	string (date) or null	-	Optional date (YYYY-MM-DD) to automatically reopen a closed lead; null clears it. Only meaningful with closed=true.	`2026-09-01`
`stat`	boolean	-	The statistics flag (separate from status): whether this lead counts toward reporting/KPIs.	`true`

{
    "status": "read",
    "junk": false,
    "closed": true,
    "reopen": "2026-09-01",
    "stat": true
}

Responses

Status	Description
`200` OK	Lead status updated

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 4009,
        "site": 0,
        "channel": "website",
        "reference": 10472,
        "name": "Jane Doe",
        "email": "jane.doe@example.com",
        "phone": "01612345678",
        "mobile": "07700900123",
        "contact": 110153,
        "type": [
            "test_drive"
        ],
        "status": {
            "id": 0,
            "name": "new"
        },
        "rating": 4,
        "summary": "Wants Saturday test drive of the Golf, asked for finance figures.",
        "created": 1781303332,
        "updated": 1781309000,
        "session": "",
        "avatar": "",
        "assign": [
            0
        ],
        "tag": [
            {
                "name": "",
                "checked": false,
                "colour": "",
                "type": "default"
            }
        ],
        "stat": false,
        "reopen": "2026-01-01",
        "data": {},
        "ai": {
            "intent": "test_drive",
            "rating_reason": "",
            "next_action": "",
            "junk": false,
            "junk_confidence": "high",
            "processed": 0
        }
    }
}

Assign

PATCH Assign Lead to Staff

PATCH /2.0/leads/{id}/assign · scope leads:write

Set the staff users a lead is assigned to. The supplied set replaces the current assignment; an empty array clears it.

Parameters (1)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.

Request body

Attribute	Type	Required	Description	Example
`assign`	array of integer	Yes	Staff user ids to assign the lead to. An empty array clears the assignment. See /reference/staff-users.	`[12,34]`

{
    "assign": [
        12,
        34
    ]
}

Responses

Status	Description
`200` OK	Assign Lead to Staff

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 4009,
        "site": 0,
        "channel": "website",
        "reference": 10472,
        "name": "Jane Doe",
        "email": "jane.doe@example.com",
        "phone": "01612345678",
        "mobile": "07700900123",
        "contact": 110153,
        "type": [
            "test_drive"
        ],
        "status": {
            "id": 0,
            "name": "new"
        },
        "rating": 4,
        "summary": "Wants Saturday test drive of the Golf, asked for finance figures.",
        "created": 1781303332,
        "updated": 1781309000,
        "session": "",
        "avatar": "",
        "assign": [
            0
        ],
        "tag": [
            {
                "name": "",
                "checked": false,
                "colour": "",
                "type": "default"
            }
        ],
        "stat": false,
        "reopen": "2026-01-01",
        "data": {},
        "ai": {
            "intent": "test_drive",
            "rating_reason": "",
            "next_action": "",
            "junk": false,
            "junk_confidence": "high",
            "processed": 0
        }
    }
}

Acknowledge

POST Acknowledge Open Leads

POST /2.0/leads/acknowledge · scope leads:write

Mark every new or unread lead (status new or new_message) as read in one call.

Responses

Status	Description
`200` OK	Acknowledge Open Leads

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "acknowledged": false
    }
}

GET List Lead Tags

GET /2.0/leads/{id}/tags · scope leads:read

List the tags applied to a lead, plus the available lead tag taxonomy.

Parameters (2)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.
`fields`	query	string	-	Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.

Responses

Status	Description
`200` OK	List Lead Tags

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "applied": [
            {
                "name": "Hot lead",
                "checked": false,
                "colour": "success",
                "type": "default"
            }
        ],
        "available": [
            {
                "name": "",
                "colour": "",
                "type": "default",
                "defaulted": false
            }
        ]
    }
}

PUT Set Lead Tags

PUT /2.0/leads/{id}/tags · scope leads:write

Replace the tags applied to a lead. Each tag name must be available in the lead tag taxonomy. The same tag items can also be set inline via the lead create/update `tag` field.

Parameters (1)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.

Request body

Attribute	Type	Required	Description	Example
`tags`	array of string	Yes	The full set of tags to apply. Each item is a tag name string, or an object { name, checked }.	`[{"name":"MOT","checked":true},{"name":"Valet","checked":false}]`

{
    "tags": [
        {
            "name": "MOT",
            "checked": true
        },
        {
            "name": "Valet",
            "checked": false
        }
    ]
}

Responses

Status	Description
`200` OK	Set Lead Tags

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "applied": [
            {
                "name": "Hot lead",
                "checked": false,
                "colour": "success",
                "type": "default"
            }
        ],
        "available": [
            {
                "name": "",
                "colour": "",
                "type": "default",
                "defaulted": false
            }
        ]
    }
}

Vehicles

GET List Lead Vehicles

GET /2.0/leads/{id}/vehicles · scope lead-vehicles:read

List vehicles associated with a lead.

Parameters (2)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.
`fields`	query	string	-	Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.

Responses

Status	Description
`200` OK	Lead vehicle associations

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": [
        {
            "id": 5521,
            "lead": 4009,
            "appointment": 0,
            "vehicle": 85481
        }
    ]
}

POST Associate Vehicle or Appointment with Lead

POST /2.0/leads/{id}/vehicles · scope lead-vehicles:write

Associate a vehicle and/or an appointment with a lead. Provide vehicle (a stock id) or vehicle_tag to link a vehicle, appointment to link an appointment, or both. At least one is required; vehicle takes precedence over vehicle_tag.

Parameters (1)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.

Request body

Attribute	Type	Required	Description	Example
`vehicle`	integer	-	Stock vehicle id to associate. Use this or vehicle_tag.	`85481`
`vehicle_tag`	string	-	Alphanumeric vehicle tag to associate, as an alternative to vehicle.	`HbSDTp97`
`appointment`	integer	-	Appointment id to link to the lead. May be supplied on its own (no vehicle) to associate just an appointment.	`747`

{
    "vehicle": 85481,
    "vehicle_tag": "HbSDTp97",
    "appointment": 747
}

Responses

Status	Description
`201` Created	Lead vehicle association created

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 5521,
        "lead": 4009,
        "appointment": 0,
        "vehicle": 85481
    }
}

DELETE Remove Lead Vehicle

DELETE /2.0/leads/{id}/vehicles/{vehicle_id} · scope lead-vehicles:delete

Remove a vehicle association from a lead.

Parameters (2)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.
`vehicle_id`	path	string	Yes	Resource identifier in the path.

Responses

Status	Description
`200` OK	Lead vehicle association deleted

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 0,
        "deleted": false
    }
}

Messages

GET List Lead Messages

GET /2.0/leads/{id}/messages · scope lead-messages:read

List the messages recorded against a lead.

Parameters (2)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.
`fields`	query	string	-	Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.

Responses

Status	Description
`200` OK	Lead messages

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": [
        {
            "id": 88213,
            "lead": 4009,
            "sender": "0",
            "message": {
                "m": "Is this still available?"
            },
            "created": 1781303332,
            "delivered": 1781303340,
            "viewed": 0
        }
    ]
}

POST Add Lead Message

POST /2.0/leads/{id}/messages · scope lead-messages:write

Add a message to a lead. By default a staff-sent message (sender = a user id) is dispatched to the lead through the reply pipeline (status becomes replied) and a customer message (sender 0) is recorded inbound (status becomes new_message). Set send=false to record without dispatching. When send is true a channel is required.

Parameters (1)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.

Request body

Attribute	Type	Required	Description	Example
`message`	string	Yes	The message body. A plain string is the common case; an object may carry structured fields (m, subject, html, text).	`Thanks for your enquiry. The vehicle is still available. When would suit you for a viewing?`
`sender`	integer	Yes	Who sent the message: 0 = the customer/lead (inbound), or a staff user id (outbound reply). See /reference/staff-users.	`0`
`send`	boolean	-	Whether to dispatch the message to the lead through the reply pipeline (email/SMS/messaging). Defaults to true for staff senders and false for customer messages. Requires a staff sender and a channel.	`true`
`channel`	enum	-	Delivery channel, required when send is true.	`email`
`notify`	boolean	-	For recorded (send=false) messages: whether to update lead status and fire live notifications. Defaults to true.	`true`
`preview`	boolean	-	When send is true, return a rendered preview without dispatching or recording.	`false`
`replies`	boolean	-	When sending by email, include the prior message thread. Defaults to true.	`true`
`plain_text`	boolean	-	When sending by email, send plain text instead of the HTML template.	`false`
`media`	object	-	Optional media attachment for messaging channels.
`media.file`	string	-	Base64 media data (optionally a data: URL). Alternative to url.
`media.type`	enum	-	i=image, vi=video.
`media.url`	string	-	Publicly reachable https URL of the media.
`media.mime`	string	-	MIME type matching the media type, e.g. image/jpeg or video/mp4.

{
    "message": "Thanks for your enquiry. The vehicle is still available. When would suit you for a viewing?",
    "sender": 0,
    "send": true,
    "channel": "email",
    "notify": true,
    "preview": false,
    "replies": true,
    "plain_text": false,
    "media": {
        "file": "",
        "type": "i",
        "url": "",
        "mime": ""
    }
}

Responses

Status	Description
`201` Created	Lead message created

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 88213,
        "lead": 4009,
        "sender": "0",
        "message": {
            "m": "Is this still available?"
        },
        "created": 1781303332,
        "delivered": 1781303340,
        "viewed": 0
    }
}

GET Get Lead Message

GET /2.0/leads/{id}/messages/{message_id} · scope lead-messages:read

Retrieve a single lead message by id.

Parameters (3)

Parameter	In	Type	Required	Description
`id`	path	string	Yes	Resource identifier in the path.
`message_id`	path	string	Yes	Resource identifier in the path.
`fields`	query	string	-	Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.

Responses

Status	Description
`200` OK	Lead message

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 88213,
        "lead": 4009,
        "sender": "0",
        "message": {
            "m": "Is this still available?"
        },
        "created": 1781303332,
        "delivered": 1781303340,
        "viewed": 0
    }
}

PATCH Update Lead Message

PATCH /2.0/leads/{id}/messages/{message_id} · scope lead-messages:write

Update a recorded lead message.

Parameters (2)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.
`message_id`	path	string	Yes	Resource identifier in the path.

Request body

Attribute	Type	Required	Description	Example
`message`	string	Yes	The message body. A plain string is the common case; an object may carry structured fields (m, subject, html, text).	`Thanks for your enquiry. The vehicle is still available. When would suit you for a viewing?`
`sender`	integer	Yes	Who sent the message: 0 = the customer/lead (inbound), or a staff user id (outbound reply). See /reference/staff-users.	`0`
`send`	boolean	-	Whether to dispatch the message to the lead through the reply pipeline (email/SMS/messaging). Defaults to true for staff senders and false for customer messages. Requires a staff sender and a channel.	`true`
`channel`	enum	-	Delivery channel, required when send is true.	`email`
`notify`	boolean	-	For recorded (send=false) messages: whether to update lead status and fire live notifications. Defaults to true.	`true`
`preview`	boolean	-	When send is true, return a rendered preview without dispatching or recording.	`false`
`replies`	boolean	-	When sending by email, include the prior message thread. Defaults to true.	`true`
`plain_text`	boolean	-	When sending by email, send plain text instead of the HTML template.	`false`
`media`	object	-	Optional media attachment for messaging channels.
`media.file`	string	-	Base64 media data (optionally a data: URL). Alternative to url.
`media.type`	enum	-	i=image, vi=video.
`media.url`	string	-	Publicly reachable https URL of the media.
`media.mime`	string	-	MIME type matching the media type, e.g. image/jpeg or video/mp4.

{
    "message": "Thanks for your enquiry. The vehicle is still available. When would suit you for a viewing?",
    "sender": 0,
    "send": true,
    "channel": "email",
    "notify": true,
    "preview": false,
    "replies": true,
    "plain_text": false,
    "media": {
        "file": "",
        "type": "i",
        "url": "",
        "mime": ""
    }
}

Responses

Status	Description
`200` OK	Lead message updated

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 88213,
        "lead": 4009,
        "sender": "0",
        "message": {
            "m": "Is this still available?"
        },
        "created": 1781303332,
        "delivered": 1781303340,
        "viewed": 0
    }
}

DELETE Delete Lead Message

DELETE /2.0/leads/{id}/messages/{message_id} · scope lead-messages:delete

Delete a lead message.

Parameters (2)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.
`message_id`	path	string	Yes	Resource identifier in the path.

Responses

Status	Description
`200` OK	Lead message deleted

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 0,
        "deleted": false
    }
}

Notes

GET List Lead Notes

GET /2.0/leads/{id}/notes · scope lead-notes:read

List the internal notes recorded against a lead.

Parameters (2)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.
`fields`	query	string	-	Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.

Responses

Status	Description
`200` OK	List Lead Notes

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": [
        {
            "id": 2,
            "lead": 4009,
            "created": 1781303332,
            "user": 12,
            "note": "Customer prefers a callback after 5pm."
        }
    ]
}

POST Add Lead Note

POST /2.0/leads/{id}/notes · scope lead-notes:write

Add an internal note to a lead, optionally attributed to a staff user.

Parameters (1)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.

Request body

Attribute	Type	Required	Description	Example
`note`	string	Yes	The note text (supports line breaks).	`Customer prefers a callback after 5pm.`
`user`	integer	-	Optional staff user id the note is attributed to, from /reference/staff-users.	`1`

{
    "note": "Customer prefers a callback after 5pm.",
    "user": 1
}

Responses

Status	Description
`200` OK	Add Lead Note

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 2,
        "lead": 4009,
        "created": 1781303332,
        "user": 12,
        "note": "Customer prefers a callback after 5pm."
    }
}

DELETE Delete Lead Note

DELETE /2.0/leads/{id}/notes/{note_id} · scope lead-notes:delete

Delete a lead note.

Parameters (2)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.
`note_id`	path	string	Yes	Resource identifier in the path.

Responses

Status	Description
`200` OK	Delete Lead Note

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 0,
        "deleted": false
    }
}

Appointments

GET List Lead Appointments

GET /2.0/leads/{id}/appointments · scope lead-appointments:read

List appointments associated with a lead.

Parameters (2)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.
`fields`	query	string	-	Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.

Responses

Status	Description
`200` OK	List Lead Appointments

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": [
        {
            "id": 0,
            "lead": 0,
            "contact": 0,
            "type": "appointment",
            "calendar": "",
            "booking": "",
            "date": "2026-01-01",
            "time": "",
            "purpose": "",
            "duration": 0,
            "duration_type": "m",
            "note": "",
            "user": [
                0
            ],
            "vehicle": 0,
            "persist": false,
            "done": false,
            "created": 0
        }
    ]
}

POST Create Lead Appointment

POST /2.0/leads/{id}/appointments · scope lead-appointments:write

Create an appointment for a lead. Provide an optional vehicle (a stock id) or vehicle_tag to also link the appointment to a vehicle of interest, mirroring the lead vehicles endpoint.

Parameters (1)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.

Request body

Attribute	Type	Required	Description	Example
`date`	string (date)	Yes	Appointment date (YYYY-MM-DD).	`2026-09-01`
`time`	string	Yes	Appointment time (HH:MM, 24-hour).	`14:30`
`type`	enum	-	The appointment kind. Defaults to appointment.	`appointment`
`purpose`	string	-	Free-text purpose/title for the appointment.	`Test drive`
`duration`	integer or null	-	Duration in the unit given by duration_type.	`30`
`duration_type`	enum	-	Duration unit: m=minutes, h=hours.	`m`
`note`	string	-	Internal note.	`Customer prefers the afternoon.`
`user`	array of integer	-	Staff user ids who own the appointment.	`[12]`
`calendar`	string	-	Calendar name. See /appointments/calendars.	`Sales`
`persist`	boolean	-	Whether the appointment persists across status changes.	`false`
`vehicle`	integer	-	Optional stock vehicle id to also link to the lead with this appointment. Use this or vehicle_tag.	`85481`
`vehicle_tag`	string	-	Optional alphanumeric vehicle tag, as an alternative to vehicle.	`HbSDTp97`

{
    "date": "2026-09-01",
    "time": "14:30",
    "type": "appointment",
    "purpose": "Test drive",
    "duration": 30,
    "duration_type": "m",
    "note": "Customer prefers the afternoon.",
    "user": [
        12
    ],
    "calendar": "Sales",
    "persist": false,
    "vehicle": 85481,
    "vehicle_tag": "HbSDTp97"
}

Responses

Status	Description
`200` OK	Create Lead Appointment

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 0,
        "lead": 0,
        "contact": 0,
        "type": "appointment",
        "calendar": "",
        "booking": "",
        "date": "2026-01-01",
        "time": "",
        "purpose": "",
        "duration": 0,
        "duration_type": "m",
        "note": "",
        "user": [
            0
        ],
        "vehicle": 0,
        "persist": false,
        "done": false,
        "created": 0
    }
}

DELETE Remove Lead Appointment

DELETE /2.0/leads/{id}/appointments/{appointment_id} · scope lead-appointments:delete

Remove an appointment from a lead.

Parameters (2)

Parameter	In	Type	Required	Description	Example
`id`	path	string	Yes	Resource identifier in the path.
`appointment_id`	path	string	Yes	Resource identifier in the path.

Responses

Status	Description
`200` OK	Remove Lead Appointment

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 0,
        "deleted": false
    }
}

Get Started

Overview

Platform

Authentication Rate Limits Errors Versioning Changelog Webhooks

Reference

Reference Data Business

CRM

Content

Blog Reviews

Stock

Vehicles Listings

Sales

Deals Invoices Orders Purchases Documents

Base URL

https://api.motordesk.com/2.0/

OpenAPI

View Schema

Credentials

Manage API Keys