On this page
Reference Data
Use reference endpoints to fetch the valid values your integration can display or submit when working with contacts, leads, appointments, vehicles, and deals.
Reference Objects
Reference endpoints return simple, stable objects. Some lists are fixed by MotorDesk, while others are business-specific.
| Object | Attributes | Description |
|---|---|---|
Tag | name string, colour string, type string, defaulted boolean | Business tag available for contacts, leads, or one vehicle stock type. |
Vehicle status | id int, name string, label string | Vehicle lifecycle status accepted by vehicle filters and writes. |
Vehicle type | id string, name string, label string | Vehicle stock type accepted by vehicle filters and writes. |
Staff user | id int, name string, role array | Business user that can be used in staff-owned fields. |
Site | id int, name string, tag string, domain string, type string, active boolean | Business site available for site-aware records. |
Booking type | id string, name string, enabled boolean, calendar string | Appointment booking type configured by the business. |
Deal stage | name string, label string | Stable deal workflow stage value and display label. |
Endpoints
| Method | Path | Scope | Description |
|---|---|---|---|
| GET | /2.0/reference/tags | reference:read | List tags for contacts, leads, or vehicles. |
| GET | /2.0/reference/vehicle-statuses | reference:read | List vehicle statuses. |
| GET | /2.0/reference/vehicle-types | reference:read | List vehicle stock types. |
| GET | /2.0/reference/staff-users | reference:read | List staff users. |
| GET | /2.0/reference/sites | reference:read | List business sites. |
| GET | /2.0/reference/booking-types | reference:read | List appointment booking types. |
| GET | /2.0/reference/deal-stages | reference:read | List deal workflow stages. |
| GET | /2.0/reference/lead-channels | reference:read | List lead message/reply channels. |
| GET | /2.0/reference/lead-types | reference:read | List lead enquiry types. |
| GET | /2.0/reference/media-backgrounds | reference:read | List vehicle media background options. |
| GET | /2.0/reference/invoice-statuses | reference:read | List invoice/order/purchase statuses. |
| GET | /2.0/reference/job-boards | reference:read | List job boards that can be applied to a vehicle. |
| GET | /2.0/reference/webhook-events | reference:read | List subscribable webhook events. |
List Tags
Returns business-specific tags for contacts, leads, or vehicles.
GET /2.0/reference/tagsParameters
| Name | Type | Required | Description |
|---|---|---|---|
resource | string | Yes | Resource to fetch tags for. Accepted values are contacts, contact, leads, lead, vehicles, and vehicle. |
type | string | Required when resource is vehicles or vehicle | Vehicle stock type: s, t, u, or r. |
Returns
Returns an object containing the normalised resource, the selected vehicle type or false, and a tags array.
{
"success": true,
"data": {
"resource": "vehicles",
"type": "s",
"tags": [
{
"name": "Retail Ready",
"colour": "green",
"type": "default",
"defaulted": false
}
]
}
}List Vehicle Statuses
Returns the vehicle statuses for a stock type. Vehicle statuses are type-aware: the numeric id is the type-independent code, but the name and label vary by vehicle type. For example code 2 is For Sale for in-stock/to-order vehicles, On Site for customer vehicles, In Use for courtesy vehicles, and Appraised for appraisals.
GET /2.0/reference/vehicle-statuses?type=appraisalParameters
type: the vehicle type, as a slug (in-stock (default), to-order, customer, courtesy, appraisal) or its stored key (s/t/u/r/a).
Returns
An object with the requested type and a statuses array (id, name, label).
GET /2.0/reference/vehicle-statuses?type=appraisal
Authorization: Bearer key_id.secret
Accept: application/json{
"success": true,
"data": {
"type": "appraisal",
"statuses": [
{
"id": 1,
"name": "added",
"label": "Added"
},
{
"id": 2,
"name": "appraised",
"label": "Appraised"
},
{
"id": 3,
"name": "accepted",
"label": "Accepted"
},
{
"id": 4,
"name": "rejected",
"label": "Rejected"
}
]
}
}List Vehicle Types
Returns the public vehicle stock types. Each has a stored key id (s/t/u/r/a), a slug name and a label. The type on a vehicle is output as the slug; on create either the slug or the key is accepted.
GET /2.0/reference/vehicle-typesParameters
No parameters.
Returns
Returns an array of vehicle type objects.
GET /2.0/reference/vehicle-types
Authorization: Bearer key_id.secret
Accept: application/json{
"success": true,
"data": [
{
"id": "s",
"name": "in-stock",
"label": "In Stock"
},
{
"id": "t",
"name": "to-order",
"label": "To Order"
},
{
"id": "u",
"name": "customer",
"label": "Customer"
},
{
"id": "r",
"name": "courtesy",
"label": "Courtesy"
},
{
"id": "a",
"name": "appraisal",
"label": "Appraisal"
}
]
}List Staff Users
Returns business users that can be used for staff-owned fields, such as contact note authors and licence checks.
GET /2.0/reference/staff-usersParameters
No parameters.
Returns
Returns an array of staff user objects. The role array depends on the business user configuration.
GET /2.0/reference/staff-users
Authorization: Bearer key_id.secret
Accept: application/json{
"success": true,
"data": [
{
"id": 123,
"name": "Alex Example",
"role": [
"admin"
]
}
]
}List Sites
Returns the main business site as id: 0, followed by active configured sites.
GET /2.0/reference/sitesParameters
No parameters.
Returns
Returns an array of site objects.
GET /2.0/reference/sites
Authorization: Bearer key_id.secret
Accept: application/json{
"success": true,
"data": [
{
"id": 0,
"name": "Example Motors",
"tag": "",
"domain": "example.com",
"type": "default",
"active": true
},
{
"id": 12,
"name": "Example Motors North",
"tag": "north",
"domain": "north.example.com",
"type": "default",
"active": true
}
]
}List Booking Types
Returns appointment booking types configured by the business. To see when a type can actually be booked, use GET /appointments/availability.
GET /2.0/reference/booking-typesParameters
No parameters.
Returns
Returns an array of booking type objects. duration_minutes is the appointment length for the type.
GET /2.0/reference/booking-types
Authorization: Bearer key_id.secret
Accept: application/json{
"success": true,
"data": [
{
"id": "custom_abcd1234efgh",
"name": "Test Drive",
"enabled": true,
"calendar": "Sales",
"duration_minutes": 30
}
]
}List Deal Stages
Returns the fixed deal workflow stages accepted by deal filters.
GET /2.0/reference/deal-stagesParameters
No parameters.
Returns
Returns an array of deal stage objects.
GET /2.0/reference/deal-stages
Authorization: Bearer key_id.secret
Accept: application/json{
"success": true,
"data": [
{
"name": "pending",
"label": "Pending"
},
{
"name": "begin",
"label": "Begin"
},
{
"name": "part_exchange",
"label": "Part Exchange"
},
{
"name": "product",
"label": "Product"
},
{
"name": "delivery_collection",
"label": "Delivery Collection"
},
{
"name": "summary",
"label": "Summary"
},
{
"name": "finance",
"label": "Finance"
},
{
"name": "payment",
"label": "Payment"
},
{
"name": "payment_partial",
"label": "Payment"
},
{
"name": "confirm",
"label": "Confirm"
},
{
"name": "handover",
"label": "Handover"
},
{
"name": "complete",
"label": "Complete"
},
{
"name": "declined",
"label": "Declined"
},
{
"name": "fatal",
"label": "Fatal"
}
]
}List Lead Channels
Returns the channels available for lead messages and replies, used by the lead message channel field.
GET /2.0/reference/lead-channelsParameters
No parameters.
Returns
Returns an array of channel objects (id, name).
GET /2.0/reference/lead-channels
Authorization: Bearer key_id.secret
Accept: application/json{
"success": true,
"data": [
{ "id": "email", "name": "Email" },
{ "id": "sms", "name": "SMS" },
{ "id": "whatsapp", "name": "WhatsApp" }
]
}List Lead Types
Returns the enquiry types used in the lead type field.
GET /2.0/reference/lead-typesParameters
No parameters.
Returns
Returns an array of lead type objects (id, name).
GET /2.0/reference/lead-types
Authorization: Bearer key_id.secret
Accept: application/json{
"success": true,
"data": [
{ "id": "test_drive", "name": "Test Drive" },
{ "id": "finance", "name": "Finance" },
{ "id": "part_exchange", "name": "Part Exchange" }
]
}List Media Backgrounds
Returns the media backgrounds available for the vehicle media edit options.background field (the default set plus any business-configured backgrounds).
GET /2.0/reference/media-backgroundsParameters
No parameters.
Returns
Returns an array of background objects (id, the value to send as options.background, plus name and key).
GET /2.0/reference/media-backgrounds
Authorization: Bearer key_id.secret
Accept: application/json{
"success": true,
"data": [
{ "id": "abstract-wave.jpg", "name": "Abstract Wave", "key": "abstract-wave" },
{ "id": "white.png", "name": "White", "key": "white" }
]
}List Invoice Statuses
Returns the status codes/names for a sales document type. Status code 2 is paid for invoices and purchases but converted for orders (an order that has been converted into an invoice).
GET /2.0/reference/invoice-statuses?type=orderParameters
type: one of invoice (default), order, or purchase.
Returns
An object with the requested type and a statuses array (id, name, label).
GET /2.0/reference/invoice-statuses?type=order
Authorization: Bearer key_id.secret
Accept: application/json{
"success": true,
"data": {
"type": "order",
"statuses": [
{ "id": 0, "name": "draft", "label": "Draft" },
{ "id": 1, "name": "issued", "label": "Issued" },
{ "id": 2, "name": "converted", "label": "Converted" },
{ "id": 3, "name": "cancelled", "label": "Cancelled" }
]
}
}List Job Boards
Returns the job boards (templates) configured for the business that can be applied to a vehicle, each with its stages and the task names within them.
GET /2.0/reference/job-boardsParameters
No parameters.
Returns
Returns an array of job board objects. apply lists the stock types the board is applied to automatically (empty when it is only applied manually).
GET /2.0/reference/job-boards
Authorization: Bearer key_id.secret
Accept: application/json{
"success": true,
"data": [
{
"id": 12,
"tag": "PREP",
"name": "Standard Prep",
"description": "Workshop preparation checklist.",
"apply": ["s"],
"stages": [
{ "name": "Inspection", "tasks": ["Road test", "Diagnostics"] },
{ "name": "Valet", "tasks": ["Wash", "Interior detail"] }
]
}
]
}List Webhook Events
Returns the webhook events available to subscribe to, each with the resource it carries and the read scope a subscription needs to receive its payload.
GET /2.0/reference/webhook-eventsParameters
No parameters.
Returns
Returns an array of webhook event objects.
GET /2.0/reference/webhook-events
Authorization: Bearer key_id.secret
Accept: application/json{
"success": true,
"data": [
{
"event": "vehicle.created",
"resource": "vehicle",
"description": "A vehicle was created.",
"scope": "vehicles:read"
},
{
"event": "lead.updated",
"resource": "lead",
"description": "A lead was updated.",
"scope": "leads:read"
}
]
}
