Service Appointment Bookings (1.4.5)

Introduction

Online service appointment booking

Definitions

The following definitions are pertinent to the usage of this API.

  • "Service appointment"
    A service appointment is an appointment the customer will make for a service or repair on a vehicle. A service appointment consist of information related to the vehicle and the requests from the customer related to the work that needs to be carried out. In addition will it contain customer requirement related to replacement transport and details of the customer and the date and time when the service should take place.

  • "Advisors" or "Service Advisors"
    A common customer-facing role in the Workshop environment that acts as the liaison between customers and the Service Department. Advisor are typically responsible for communicating with customers regarding vehicle problems and repair timeline, and expressing customer concerns to service department. The online booking website might offer the possibility to book a specific service advisor for the booking which is an optional function.
    Advisor are optional in the process and some back-end systems will not use service advisors.

  • "Vehicle Make"
    The vehicle make is the unique reference to the manufacturer of the vehicle. This is a standardized list of of vehicle manufacturers.The APIs will use this information to offer the appropriate information for the type of vehicle to be serviced.

  • "Service product"
    A service product is an option which the customer could choose in the service appointment booking process and describes the work that needs to be done to the vehicle.

  • "Booking option"
    Appointment options define if and what the requirements of the customer are related booking. With an appointment option is the customer able to select services the dealer is offering. The availability of appointment options is depending on what the dealer offers but also depending on the availability of the resources required.

  • "Advisor group"
    Service advisors might work in one or more groups. These groups provide an optional filter on the advisor related resources. The actual implementation of this grouping is depending on the capabilities of the backend system and it should be considered as an optional filter possibility.

Changes in this version:

[1.4.5]

  • Added vehicle details to Appointment Booking Option endpoint
  • Added model filter to Appointment Booking Option endpoint

[1.4.4]

  • Added Fuel Type & Electric Vehicle Type to ServiceProduct endpoint

[1.4.3]

  • Fixed Date Format Issues in availability endpoints
  • Removed Country Code validation
  • Created custom address class for Appointments to support current implementations with consumers(in future we will use common address component)
  • Made username & userId optional in Metadata --> Audit Data

[1.4.2]

  • Fixed issues by comparing with Bundled api

[1.4.1]

  • Fixed the date time conversion issue

[1.4.0]

  • Created a stand alone Appointment project by decoupling it from bundled-API)
  • Changed the schema of few models to match with bundled-API Appointment model

[1.3.0]

  • Added vehicle details to ServiceProduct endpoint

[1.2.2]

  • Added new 'DROP_OFF' enum value to TransportationTypeEnum

[1.2.1] (22-04-2021)

  • Change to Keyloop

[1.2.0]

  • [MIDWARE-2042] GET Appointment by ID added
  • [MIDWARE-2334] Indicative prices on service products and booking options

[1.1.0]

  • [MIDWARE-1996] Add new vehicle class LIGHTTRUCK to differientiate between light and havy duty trucks.

[1.0.2]

  • [MIDWARE-1750] Add 'advisorRequired' flag on additional service products in the availability request

[1.0.1]

  • [MIDWARE-1576] Add advisor group support

[1.0.0]

  • Initial version based on existing swagger definition

Contact Information

Service Appointments: Service Advisor

Get service advisors

Get Service Advisor Groups

This resource allows the user to retrieve details of advisor groups available in the backend system. These gorups can be used for:

  • Filter advisors
  • Filter advisor availability

    Note: Advisor groups are optional in the backend systems and might not be available for some of these systems.
Authorizations:
OAuth2
query Parameters
description
string

Description of the advisor group

page
integer >= 1
Default: 1
Examples:
  • page=1 - Example of for page query parameter
  • page=10 - Example of for page query parameter

A non-zero integer representing the page of the results

pageSize
integer >= 50
Default: 50
Examples:
  • pageSize=50 - Example of for pageSize query parameter
  • pageSize=500 - Example of for pageSize query parameter

A non-negative, non-zero integer indicating the maximum number of results to return at one time

Responses

Response samples

Content type
application/json
{
  • "totalItems": 4,
  • "totalPages": 1,
  • "advisorGroups": [
    ],
  • "links": [
    ]
}

Service advisor search

This resource allows the user to retrieve a list of valid service advisor for a given vehicle type. The make and vehicle class will be used to filter the advisors based on their capability. The advisor details retrieved can be used in conjunction with other APIs to achieve specific outcomes, such as:

  • Obtaining detailed information about a specific advisor.
  • Obtaining detailed information planning availability.
  • Retreive an picture of the advisor.
  • Adding the advisor to a service appointment.

Authorizations:
OAuth2
query Parameters
make
string
Example: make=MERCEDES-BENZ

The standarised code of the vehicle manufacturer to filter the advisors based on their capability.

vehicleClass
string (Vehicle class)
Enum: "UNKNOWN" "CAR" "VAN" "MOTORCYCLE" "TRUCK" "OTHER" "NOTAPPLICABLE" "BUS" "LIGHTTRUCK"
Example: vehicleClass=CAR

The classification of the vehicle to filter the advisors based on their capability.

name
string

Name of the advisor

page
integer >= 1
Default: 1
Examples:
  • page=1 - Example of for page query parameter
  • page=10 - Example of for page query parameter

A non-zero integer representing the page of the results

pageSize
integer >= 50
Default: 50
Examples:
  • pageSize=50 - Example of for pageSize query parameter
  • pageSize=500 - Example of for pageSize query parameter

A non-negative, non-zero integer indicating the maximum number of results to return at one time

Responses

Response samples

Content type
application/json
{
  • "totalItems": 4,
  • "totalPages": 1,
  • "advisors": [
    ],
  • "links": [
    ]
}

Get Service Advisor

This resource allows the user to retrieve details of a specific advisor identified by the unique advisor ID. The advisor details retrieved can be used in conjunction with other APIs to achieve specific outcomes, such as:

  • Obtaining detailed information planning availability.
  • Retreive an picture of the advisor.
  • Adding the advisor to a service appointment.

Authorizations:
OAuth2
path Parameters
advisorId
required
string

Advisor unique id

Responses

Response samples

Content type
application/json
{
  • "advisorId": "SA1",
  • "name": "John Doo",
  • "jobTitle": "Service advisor passenger car",
  • "email": "john.doo@mail.com",
  • "imageUrl": "/appointment/sample/sample/v1/docs/imageid.jpg",
  • "groups": [
    ],
  • "links": [
    ]
}

Get document

This resource allows the user to retrieve the image of the advisor.

Authorizations:
OAuth2
path Parameters
documentId
required
string

Unique ID of the document

Responses

Response samples

Content type
application/json
{
  • "correlationId": "48fb4cd3-2ef6-4479-bea1-7c92721b988c",
  • "message": "Invalid request",
  • "details": [
    ],
  • "links": [
    ]
}

Service Appointments: Availability

Check the availability within the workshop planning

Get Combined Appointment Availability

Retrieve availability for creating a service booking.
This response will provide all the possible time slots within the date range for the provided advisors, service products and booking options.

Authorizations:
OAuth2
Request Body schema: application/json
dateFrom
string or null <date>

The start date for checking the availability (default current date)

dateTo
string or null <date>

The end date for checking the availability (default until the end of the month)

object (AppointmentPlanningVehicle)
advisorIds
Array of strings unique

List of service advisor IDs. If not provided all available service advisor IDs are reported.

advisorGroupIds
Array of strings unique

List of service advisor group IDs. If not provided all available service advisor IDs are reported without filtering of the advisor group ID.

appointmentOptionIds
Array of strings unique

List of booking option IDs for which the availability should be checked. If not provided all applicable and available booking option IDs are reported.

serviceProductIds
Array of strings unique

List of service product IDs for which the availability should be checked.

Array of objects (AppointmentPlanningServiceProduct)

List of additional service products for which the availability should be checked.

Responses

Request samples

Content type
application/json
{
  • "dateFrom": "2023-05-05T00:00:00.000Z",
  • "dateTo": "2023-05-05T00:00:00.000Z",
  • "vehicle": {
    },
  • "advisorIds": [
    ],
  • "advisorGroupIds": [
    ],
  • "appointmentOptionIds": [
    ],
  • "serviceProductIds": [
    ],
  • "additionalServiceProducts": [
    ]
}

Response samples

Content type
application/json
{
  • "appointmentAvailabilities": [
    ]
}

Get Multiple Advisor Availability

Service advisors might be booked on a service appointment to meet the customer before and/or after the vehicle service to explain the work to be done on the vehicle. This API will provide the information on dates and times when the service advisor is available for these booking. The service advisors availability might be listed based on a date range, their capabilities on vehicle makes and vehicle class or for a specific service advisor.
Use the /appointment/availability request instead if combined availability is required.

Authorizations:
OAuth2
query Parameters
make
string
Example: make=MERCEDES-BENZ

The standarised code of the vehicle manufacturer to filter the advisors based on their capability.

vehicleClass
string (Vehicle class)
Enum: "UNKNOWN" "CAR" "VAN" "MOTORCYCLE" "TRUCK" "OTHER" "NOTAPPLICABLE" "BUS" "LIGHTTRUCK"
Example: vehicleClass=CAR

The classification of the vehicle to filter the advisors based on their capability.

advisorIds
Array of strings

List of advisor IDs to filter the availability response.

advisorGroupIds
Array of strings unique

List of advisor groups IDs to filter the availability response.

dateFrom
string <date>

The start date for checking the availability. If the date is ommited is the current date used.

dateTo
string <date>

The end date for checking the availability. If this date is ommited is the validation checked until the end of the month provided in the dateFrom parameter.

Responses

Response samples

Content type
application/json
{
  • "advisorAvailabilities": [
    ]
}

Get Advisor Availability

This resource allows the user to retrieve information on dates and times when the service advisor is available for meeting the customer for a service booking. The availability response is for the advisor only, availability of the advisor in combination with the work required can be retrieved with the combined availability request.
Use the /appointment/availability request instead if combined availability is required.

Authorizations:
OAuth2
path Parameters
advisorId
required
string

Advisor unique id

query Parameters
dateFrom
string <date>

The start date for checking the availability. If the date is ommited is the current date used.

dateTo
string <date>

The end date for checking the availability. If this date is ommited is the validation checked until the end of the month provided in the dateFrom parameter.

Responses

Response samples

Content type
application/json
{
  • "advisorAvailabilities": [
    ]
}

Get Appointment Option Availability

Retrieve booking availability for creating a service booking for the motability options the customer can choose. This response will provide all the possible time slots within the date range for the provided booking options.
Use the /appointment/availability request instead if combined availability is required.

Authorizations:
OAuth2
Request Body schema: application/json
dateFrom
string or null <date>

The start date for checking the availability (default current date)

dateTo
string or null <date>

The end date for checking the availability (default until the end of the month)

object (AppointmentPlanningVehicle)
appointmentOptionIds
Array of strings unique

List of booking option IDs for which the availability should be checked. If not provided all applicable and available booking option IDs are reported.

Responses

Request samples

Content type
application/json
{
  • "dateFrom": "2023-05-05T00:00:00.000Z",
  • "dateTo": "2023-05-05T00:00:00.000Z",
  • "vehicle": {
    },
  • "appointmentOptionIds": [
    ]
}

Response samples

Content type
application/json
{
  • "appointmentOptionAvailabilities": [
    ]
}

Get Service Product Availability

Retrieve booking availability for creating a service booking based on the work that needs to be done. This response will provide all the possible time slots within the date range when the requested work can be carried out.
Use the /appointment/availability request instead if combined availability is required.

Authorizations:
OAuth2
Request Body schema: application/json
dateFrom
string or null <date>

The start date for checking the availability (default current date)

dateTo
string or null <date>

The end date for checking the availability (default until the end of the month)

object (AppointmentPlanningVehicle)
transportationType
string (TransportationTypeEnum)
Enum: "NONE" "WAITER" "SHUTTLE" "REPLACEMENT_TRANSPORT" "COLLECT_DELIVER" "DROP_OFF"

Type of booking option

serviceProductIds
Array of strings unique

List of service product IDs for which the availability should be checked.

Array of objects (AppointmentPlanningServiceProduct)

List of additional service products for which the availability should be checked.

Responses

Request samples

Content type
application/json
{
  • "dateFrom": "2023-05-05T00:00:00.000Z",
  • "dateTo": "2023-05-05T00:00:00.000Z",
  • "vehicle": {
    },
  • "transportationType": "NONE",
  • "serviceProductIds": [
    ],
  • "additionalServiceProducts": [
    ]
}

Response samples

Content type
application/json
{
  • "appointmentServiceAvailabilities": [
    ]
}

Service Appointments

Create or cancel a service appointment

Create Service Appointment

Create a service appointment.
An appointment is the booking of a vehicle at a dealership to have work done on it. It will include the date and time the vehicle is expected, and when the work is expected to be completed. An appointment will move to a repair order once the vehicle arrives at the dealership and work is begun.
The Appointments API provides the ability for users provide information on the contact person, the vehicle to be served, the work that needs to be done, the requirements related to booking options (e.g. replacement transport) and the date and time of the appointment. All this information combined can then be used to create a new appointment booking.

Possible responses:
Created (201) in case the booking has been created, the appointment reference ID will be provided.
Accepted (202) in case the booking could not directly be created, the appointment reference ID will be provided but might be a temporary ID.
Conflict (409) in case the booking could not be created due to a conflict in the workshop planning

Authorizations:
OAuth2
Request Body schema: application/json
object (AppointmentDetailsCreate)
object (AppointmentBookingCustomer)
object (VehicleBaseModel)
object (AppointmentBookingOption)
Array of objects (AppointmentBookingServiceProduct)
Array of objects (AppointmentBookingAdditionalServiceProduct)
object

Metadata for the action

Responses

Request samples

Content type
application/json
{
  • "details": {
    },
  • "customer": {
    },
  • "vehicle": {
    },
  • "bookingOption": {
    },
  • "serviceProducts": [
    ],
  • "additionalServiceProducts": [
    ],
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "appointmentId": "5200196a-5dee-e811-9112-005056983362",
  • "details": {
    },
  • "customer": {
    },
  • "vehicle": {
    },
  • "bookingOption": {
    },
  • "serviceProducts": [
    ],
  • "additionalServiceProducts": [
    ]
}

Get service appointment details based on appointment ID

Get basic details about the created service appointment based on the appointment ID provided in the create appointment response

Authorizations:
OAuth2
path Parameters
appointmentId
required
string

Responses

Response samples

Content type
application/json
{
  • "appointmentId": "5200196a-5dee-e811-9112-005056983362",
  • "details": {
    },
  • "customer": {
    },
  • "vehicle": {
    },
  • "bookingOption": {
    }
}

Delete Service Appointment

Cancels the appointment booking based on the booking ID.

Possible responses:
No content (204) if the appointment could be cancelled, ‘No content’ (204) is returned.
Accepted (202) if the appointment could not be cancelled directly and a manual action of the service advisor is required.
Forbidden (403) if the appointment could not be cancelled due to restrictions. The response will indicate the reason.
Not Found (404) if the appointment has not been found and cannot be cancelled.

Authorizations:
OAuth2
path Parameters
appointmentId
required
string
Request Body schema: application/json
object

Metadata for the action

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "correlationId": "48fb4cd3-2ef6-4479-bea1-7c92721b988c",
  • "message": "Invalid request",
  • "details": [
    ],
  • "links": [
    ]
}

Service Appointments: Booking options

Get appointment booking options

Find Appointment Options

Get the options for a given appointment using the appointment Id

Authorizations:
OAuth2
query Parameters
appointmentOptionId
Array of strings

Appointment option unique identification

make
string

Vehicle make code

vehicleClass
string (Vehicle class)
Enum: "UNKNOWN" "CAR" "VAN" "MOTORCYCLE" "TRUCK" "OTHER" "NOTAPPLICABLE" "BUS" "LIGHTTRUCK"
Example: vehicleClass=CAR

Vehicle type classification

model
string

Vehicle model code

FuelType
string
Enum: "DIESEL" "PETROL" "ELECTRIC" "HYBRID" "LPG" "OTHER"

Fuel Type

ElectricVehicleType
string
Enum: "BEV" "PHEV" "HEV" "FCEV"

Electric Vehicle Type

Responses

Response samples

Content type
application/json
{
  • "totalItems": 4,
  • "totalPages": 1,
  • "appointmentOptions": [
    ]
}

Get Appointment Option

Get details of option for an appointment using an appointmentOptionId

Authorizations:
OAuth2
path Parameters
appointmentOptionId
required
string

Appointment option unique ID

Responses

Response samples

Content type
application/json
{
  • "appointmentOptionId": "5100196a-5dee-e811-9112-005056983362",
  • "description": "Customer waiting",
  • "notes": "string",
  • "transportationType": "NONE",
  • "price": {
    },
  • "indicativePrice": {
    },
  • "vehicle": {
    },
  • "links": [
    ]
}

Service Appointments: Appointment service products

Get service products

Find Service Categories

Get the service categories for an appointment

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "serviceCategories": [
    ]
}

Get Service Category

Get a service category using a serviceCategoryCode

Authorizations:
OAuth2
path Parameters
serviceCategoryCode
required
string <= 25 characters

Service category code

Responses

Response samples

Content type
application/json
{
  • "code": "10",
  • "description": "Service"
}

Find Service Products

Get the service products for an appointment

Authorizations:
OAuth2
query Parameters
make
string

Vehicle make code

vehicleClass
string (Vehicle class)
Enum: "UNKNOWN" "CAR" "VAN" "MOTORCYCLE" "TRUCK" "OTHER" "NOTAPPLICABLE" "BUS" "LIGHTTRUCK"
Example: vehicleClass=CAR

Vehicle type classification

model
string

Vehicle model code

firstRegistrationDate
string <date-time>
Example: firstRegistrationDate=2023-03-28T07:00:00.000Z

First registration date of the vehicle

mileageUnit
string
Enum: "KM" "MILES" "HOURS"

Unit of mileage provided

mileage
integer <int32>

Current vehicle mileage

FuelType
string
Enum: "DIESEL" "PETROL" "ELECTRIC" "HYBRID" "LPG" "OTHER"

Fuel Type

ElectricVehicleType
string
Enum: "BEV" "PHEV" "HEV" "FCEV"

Electric Vehicle Type

page
integer >= 1
Default: 1
Examples:
  • page=1 - Example of for page query parameter
  • page=10 - Example of for page query parameter

A non-zero integer representing the page of the results

pageSize
integer >= 50
Default: 50
Examples:
  • pageSize=50 - Example of for pageSize query parameter
  • pageSize=500 - Example of for pageSize query parameter

A non-negative, non-zero integer indicating the maximum number of results to return at one time

Responses

Response samples

Content type
application/json
{
  • "totalItems": 4,
  • "totalPages": 1,
  • "serviceProducts": [
    ],
  • "links": [
    ]
}

Get Service Product

Get a service product using a serviceProductId

Authorizations:
OAuth2
path Parameters
serviceProductId
required
string

Responses

Response samples

Content type
application/json
{
  • "serviceProductId": "5100196a-5dee-e811-9112-005056983362",
  • "vehicle": {
    },
  • "description": "string",
  • "notes": "Full service plus",
  • "serviceCategory": {
    },
  • "requiredTimeInMinutes": 45,
  • "price": {
    },
  • "indicativePrice": {
    },
  • "advisorRequired": true,
  • "links": [
    ]
}