Use reference endpoints to fetch the valid values your integration can display or submit when working with contacts, leads, appointments, vehicles, and deals.
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. |
| 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. |
Returns business-specific tags for contacts, leads, or vehicles.
GET /2.0/reference/tags| 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 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
}
]
}
}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=appraisaltype: the vehicle type, as a slug (in-stock (default), to-order, customer, courtesy, appraisal) or its stored key (s/t/u/r/a).
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"
}
]
}
}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-typesNo parameters.
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"
}
]
}Returns business users that can be used for staff-owned fields, such as contact note authors and licence checks.
GET /2.0/reference/staff-usersNo parameters.
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"
]
}
]
}Returns the main business site as id: 0, followed by active configured sites.
GET /2.0/reference/sitesNo parameters.
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
}
]
}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-typesNo parameters.
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
}
]
}Returns the fixed deal workflow stages accepted by deal filters.
GET /2.0/reference/deal-stagesNo parameters.
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"
}
]
}Returns the channels available for lead messages and replies, used by the lead message channel field.
GET /2.0/reference/lead-channelsNo parameters.
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" }
]
}Returns the enquiry types used in the lead type field.
GET /2.0/reference/lead-typesNo parameters.
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" }
]
}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-backgroundsNo parameters.
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" }
]
}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=ordertype: one of invoice (default), order, or purchase.
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" }
]
}
}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-boardsNo parameters.
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"] }
]
}
]
}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-eventsNo parameters.
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"
}
]
}