[← API v2 Overview](https://motordesk.com/api-docs/v2/)

# 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`](https://motordesk.com/api-docs/v2/reference/#list-tags) | `reference:read` | List tags for contacts, leads, or vehicles. |
| GET | [`/2.0/reference/vehicle-statuses`](https://motordesk.com/api-docs/v2/reference/#list-vehicle-statuses) | `reference:read` | List vehicle statuses. |
| GET | [`/2.0/reference/vehicle-types`](https://motordesk.com/api-docs/v2/reference/#list-vehicle-types) | `reference:read` | List vehicle stock types. |
| GET | [`/2.0/reference/staff-users`](https://motordesk.com/api-docs/v2/reference/#list-staff-users) | `reference:read` | List staff users. |
| GET | [`/2.0/reference/sites`](https://motordesk.com/api-docs/v2/reference/#list-sites) | `reference:read` | List business sites. |
| GET | [`/2.0/reference/booking-types`](https://motordesk.com/api-docs/v2/reference/#list-booking-types) | `reference:read` | List appointment booking types. |
| GET | [`/2.0/reference/deal-stages`](https://motordesk.com/api-docs/v2/reference/#list-deal-stages) | `reference:read` | List deal workflow stages. |
| GET | [`/2.0/reference/lead-channels`](https://motordesk.com/api-docs/v2/reference/#list-lead-channels) | `reference:read` | List lead message/reply channels. |
| GET | [`/2.0/reference/lead-types`](https://motordesk.com/api-docs/v2/reference/#list-lead-types) | `reference:read` | List lead enquiry types. |
| GET | [`/2.0/reference/media-backgrounds`](https://motordesk.com/api-docs/v2/reference/#list-media-backgrounds) | `reference:read` | List vehicle media background options. |
| GET | [`/2.0/reference/invoice-statuses`](https://motordesk.com/api-docs/v2/reference/#list-invoice-statuses) | `reference:read` | List invoice/order/purchase statuses. |
| GET | [`/2.0/reference/job-boards`](https://motordesk.com/api-docs/v2/reference/#list-job-boards) | `reference:read` | List job boards that can be applied to a vehicle. |
| GET | [`/2.0/reference/webhook-events`](https://motordesk.com/api-docs/v2/reference/#list-webhook-events) | `reference:read` | List subscribable webhook events. |

## List Tags

Returns business-specific tags for contacts, leads, or vehicles.

```
GET /2.0/reference/tags
```

### Parameters

| 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.

Request

```
GET /2.0/reference/tags?resource=vehicles&type=s
Authorization: Bearer key_id.secret
Accept: application/json
```

Response

```json
{
  "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=appraisal
```

### Parameters

`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`).

Request

```
GET /2.0/reference/vehicle-statuses?type=appraisal
Authorization: Bearer key_id.secret
Accept: application/json
```

Response

```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-types
```

### Parameters

No parameters.

### Returns

Returns an array of vehicle type objects.

Request

```
GET /2.0/reference/vehicle-types
Authorization: Bearer key_id.secret
Accept: application/json
```

Response

```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-users
```

### Parameters

No parameters.

### Returns

Returns an array of staff user objects. The `role` array depends on the business user configuration.

Request

```
GET /2.0/reference/staff-users
Authorization: Bearer key_id.secret
Accept: application/json
```

Response

```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/sites
```

### Parameters

No parameters.

### Returns

Returns an array of site objects.

Request

```
GET /2.0/reference/sites
Authorization: Bearer key_id.secret
Accept: application/json
```

Response

```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`](https://motordesk.com/api-docs/v2/appointments/#booking-availability).

```
GET /2.0/reference/booking-types
```

### Parameters

No parameters.

### Returns

Returns an array of booking type objects. `duration_minutes` is the appointment length for the type.

Request

```
GET /2.0/reference/booking-types
Authorization: Bearer key_id.secret
Accept: application/json
```

Response

```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-stages
```

### Parameters

No parameters.

### Returns

Returns an array of deal stage objects.

Request

```
GET /2.0/reference/deal-stages
Authorization: Bearer key_id.secret
Accept: application/json
```

Response

```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-channels
```

### Parameters

No parameters.

### Returns

Returns an array of channel objects (`id`, `name`).

Request

```
GET /2.0/reference/lead-channels
Authorization: Bearer key_id.secret
Accept: application/json
```

Response

```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-types
```

### Parameters

No parameters.

### Returns

Returns an array of lead type objects (`id`, `name`).

Request

```
GET /2.0/reference/lead-types
Authorization: Bearer key_id.secret
Accept: application/json
```

Response

```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-backgrounds
```

### Parameters

No parameters.

### Returns

Returns an array of background objects (`id`, the value to send as `options.background`, plus `name` and `key`).

Request

```
GET /2.0/reference/media-backgrounds
Authorization: Bearer key_id.secret
Accept: application/json
```

Response

```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=order
```

### Parameters

`type`: one of `invoice` (default), `order`, or `purchase`.

### Returns

An object with the requested `type` and a `statuses` array (`id`, `name`, `label`).

Request

```
GET /2.0/reference/invoice-statuses?type=order
Authorization: Bearer key_id.secret
Accept: application/json
```

Response

```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-boards
```

### Parameters

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).

Request

```
GET /2.0/reference/job-boards
Authorization: Bearer key_id.secret
Accept: application/json
```

Response

```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-events
```

### Parameters

No parameters.

### Returns

Returns an array of webhook event objects.

Request

```
GET /2.0/reference/webhook-events
Authorization: Bearer key_id.secret
Accept: application/json
```

Response

```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"
    }
  ]
}
```