Service Appointment Bookings (1.4.5)
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
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:
query Parameters
description | string Description of the advisor group |
page | integer >= 1 Default: 1 Examples:
A non-zero integer representing the page of the results |
pageSize | integer >= 50 Default: 50 Examples:
A non-negative, non-zero integer indicating the maximum number of results to return at one time |
Responses
Response samples
- 200
{- "totalItems": 4,
- "totalPages": 1,
- "advisorGroups": [
- {
- "groupId": "ES",
- "description": "Express Service"
}
], - "links": [
- {
- "method": "GET",
- "rel": "self",
- "href": "string",
- "title": "string"
}
]
}
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:
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:
A non-zero integer representing the page of the results |
pageSize | integer >= 50 Default: 50 Examples:
A non-negative, non-zero integer indicating the maximum number of results to return at one time |
Responses
Response samples
- 200
{- "totalItems": 4,
- "totalPages": 1,
- "advisors": [
- {
- "advisorId": "SA1",
- "name": "John Doo",
- "jobTitle": "Service advisor passenger car",
- "email": "john.doo@mail.com",
- "imageUrl": "/appointment/sample/sample/v1/docs/imageid.jpg"
}
], - "links": [
- {
- "method": "GET",
- "rel": "self",
- "href": "string",
- "title": "string"
}
]
}
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:
path Parameters
advisorId required | string Advisor unique id |
Responses
Response samples
- 200
- 404
{- "advisorId": "SA1",
- "name": "John Doo",
- "jobTitle": "Service advisor passenger car",
- "email": "john.doo@mail.com",
- "imageUrl": "/appointment/sample/sample/v1/docs/imageid.jpg",
- "groups": [
- {
- "groupId": "ES",
- "description": "Express Service"
}
], - "links": [
- {
- "method": "GET",
- "rel": "self",
- "href": "string",
- "title": "string"
}
]
}
Get document
This resource allows the user to retrieve the image of the advisor.
Authorizations:
path Parameters
documentId required | string Unique ID of the document |
Responses
Response samples
- 404
{- "correlationId": "48fb4cd3-2ef6-4479-bea1-7c92721b988c",
- "message": "Invalid request",
- "details": [
- {
- "field": "Status",
- "value": "string",
- "issue": "The value 'XYZ' is not valid."
}
], - "links": [
- {
- "method": "GET",
- "rel": "self",
- "href": "string",
- "title": "string"
}
]
}
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:
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
- Payload
{- "dateFrom": "2023-05-05T00:00:00.000Z",
- "dateTo": "2023-05-05T00:00:00.000Z",
- "vehicle": {
- "vehicleId": "4e00196a-5dee-e811-9112-005056983362",
- "make": "PORSCHE",
- "class": "CAR",
- "identification": {
- "vin": "1FTHF25H1JNB79097",
- "chassis": "68060",
- "licensePlate": "TOY-123",
- "engineNumber": "12345678"
}
}, - "advisorIds": [
- "string"
], - "advisorGroupIds": [
- "string"
], - "appointmentOptionIds": [
- "string"
], - "serviceProductIds": [
- "string"
], - "additionalServiceProducts": [
- {
- "description": "string",
- "advisorRequired": false,
- "menus": [
- {
- "sequenceNumber": 1,
- "description": "Main service",
- "menuCode": "SERVICE",
- "brandCode": "FORD",
- "laborItems": [
- {
- "sequenceNumber": 2,
- "description": "Oil check",
- "laborCode": "OILCHECK",
- "brandCode": "FORD",
- "allowedTimeInMinutes": 45
}
], - "partItems": [
- {
- "sequenceNumber": 3,
- "description": "CASTROL EDGE SPORT 5W-30",
- "partId": "ZZCASTROL-SW30",
- "partCode": "5010321000143",
- "brandCode": "FORD",
- "unitOfMeasure": "LITERS",
- "quantity": 2
}
], - "textItems": [
- {
- "sequenceNumber": 4,
- "notes": "Noice at the left front while breaking"
}
]
}
], - "laborItems": [
- {
- "sequenceNumber": 2,
- "description": "Oil check",
- "laborCode": "OILCHECK",
- "brandCode": "FORD",
- "allowedTimeInMinutes": 45
}
], - "partItems": [
- {
- "sequenceNumber": 3,
- "description": "CASTROL EDGE SPORT 5W-30",
- "partId": "ZZCASTROL-SW30",
- "partCode": "5010321000143",
- "brandCode": "FORD",
- "unitOfMeasure": "LITERS",
- "quantity": 2
}
], - "textItems": [
- {
- "sequenceNumber": 4,
- "notes": "Noice at the left front while breaking"
}
]
}
]
}
Response samples
- 200
- 404
{- "appointmentAvailabilities": [
- {
- "date": "2023-05-05T00:00:00.000Z",
- "capacityFreePercentage": 50,
- "slotTime": 15,
- "timeSlots": [
- {
- "startDateTime": "2021-04-14T07:00:00.000Z",
- "endDateTime": "2021-04-14T09:00:00.000Z",
- "available": true,
- "availableAdvisors": [
- {
- "advisorId": "SA12345"
}
], - "availableAppointmentOptions": [
- {
- "appointmentOptionId": "d3d57990-2747-4019-a961-729dba0dfad4"
}
]
}
]
}
]
}
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:
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
- 200
{- "advisorAvailabilities": [
- {
- "date": "2019-08-24",
- "capacityFreePercentage": 50,
- "slotTime": 15,
- "timeSlots": [
- {
- "startDateTime": "2021-04-14T07:00:00.000Z",
- "endDateTime": "2021-04-14T09:00:00.000Z",
- "available": true,
- "availableAdvisors": [
- {
- "advisorId": "SA12345"
}
]
}
]
}
]
}
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:
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
- 200
- 404
{- "advisorAvailabilities": [
- {
- "date": "2019-08-24",
- "capacityFreePercentage": 50,
- "slotTime": 15,
- "timeSlots": [
- {
- "startDateTime": "2021-04-14T07:00:00.000Z",
- "endDateTime": "2021-04-14T09:00:00.000Z",
- "available": true,
- "availableAdvisors": [
- {
- "advisorId": "SA12345"
}
]
}
]
}
]
}
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:
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
- Payload
{- "dateFrom": "2023-05-05T00:00:00.000Z",
- "dateTo": "2023-05-05T00:00:00.000Z",
- "vehicle": {
- "vehicleId": "4e00196a-5dee-e811-9112-005056983362",
- "make": "PORSCHE",
- "class": "CAR",
- "identification": {
- "vin": "1FTHF25H1JNB79097",
- "chassis": "68060",
- "licensePlate": "TOY-123",
- "engineNumber": "12345678"
}
}, - "appointmentOptionIds": [
- "string"
]
}
Response samples
- 200
{- "appointmentOptionAvailabilities": [
- {
- "date": "2023-05-05T00:00:00.000Z",
- "capacityFreePercentage": 50,
- "timeSlots": [
- {
- "startDateTime": "2021-04-14T07:00:00.000Z",
- "endDateTime": "2021-04-14T09:00:00.000Z",
- "available": true,
- "availableAppointmentOptions": [
- {
- "appointmentOptionId": "d3d57990-2747-4019-a961-729dba0dfad4"
}
]
}
]
}
]
}
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:
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
- Payload
{- "dateFrom": "2023-05-05T00:00:00.000Z",
- "dateTo": "2023-05-05T00:00:00.000Z",
- "vehicle": {
- "vehicleId": "4e00196a-5dee-e811-9112-005056983362",
- "make": "PORSCHE",
- "class": "CAR",
- "identification": {
- "vin": "1FTHF25H1JNB79097",
- "chassis": "68060",
- "licensePlate": "TOY-123",
- "engineNumber": "12345678"
}
}, - "transportationType": "NONE",
- "serviceProductIds": [
- "string"
], - "additionalServiceProducts": [
- {
- "description": "string",
- "advisorRequired": false,
- "menus": [
- {
- "sequenceNumber": 1,
- "description": "Main service",
- "menuCode": "SERVICE",
- "brandCode": "FORD",
- "laborItems": [
- {
- "sequenceNumber": 2,
- "description": "Oil check",
- "laborCode": "OILCHECK",
- "brandCode": "FORD",
- "allowedTimeInMinutes": 45
}
], - "partItems": [
- {
- "sequenceNumber": 3,
- "description": "CASTROL EDGE SPORT 5W-30",
- "partId": "ZZCASTROL-SW30",
- "partCode": "5010321000143",
- "brandCode": "FORD",
- "unitOfMeasure": "LITERS",
- "quantity": 2
}
], - "textItems": [
- {
- "sequenceNumber": 4,
- "notes": "Noice at the left front while breaking"
}
]
}
], - "laborItems": [
- {
- "sequenceNumber": 2,
- "description": "Oil check",
- "laborCode": "OILCHECK",
- "brandCode": "FORD",
- "allowedTimeInMinutes": 45
}
], - "partItems": [
- {
- "sequenceNumber": 3,
- "description": "CASTROL EDGE SPORT 5W-30",
- "partId": "ZZCASTROL-SW30",
- "partCode": "5010321000143",
- "brandCode": "FORD",
- "unitOfMeasure": "LITERS",
- "quantity": 2
}
], - "textItems": [
- {
- "sequenceNumber": 4,
- "notes": "Noice at the left front while breaking"
}
]
}
]
}
Response samples
- 200
{- "appointmentServiceAvailabilities": [
- {
- "date": "2023-05-05T00:00:00.000Z",
- "capacityFreePercentage": 50,
- "timeSlots": [
- {
- "startDateTime": "2021-04-14T07:00:00.000Z",
- "endDateTime": "2021-04-14T09:00:00.000Z",
- "available": true
}
]
}
]
}
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:
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
- Payload
{- "details": {
- "externalReference": "REF123",
- "customerNotes": "Please do not wash my car",
- "dueInDateTime": "2021-04-14T07:00:00.000Z",
- "dueOutDateTime": "2021-04-14T09:00:00.000Z",
- "advisorRequired": true,
- "contactAdvisorId": "string"
}, - "customer": {
- "customerId": "4e00196a-5dee-e811-9112-005056983362",
- "names": {
- "familyName": "string",
- "familyName2": "string",
- "middleName": "string",
- "givenName": "string",
- "preferredName": "string",
- "initials": "string",
- "salutation": "string",
- "titleCommon": "string"
}, - "address": {
- "streetType": "Avenue",
- "streetName": "Mill Lane",
- "houseNumber": "7",
- "buildingName": "Avance Hirise",
- "floorNumber": "3",
- "doorNumber": "12345",
- "blockName": "Block C",
- "estate": "Royal Estate",
- "postalCode": "SE4 1UU",
- "suburb": "Seafield",
- "city": "Glasgow",
- "county": "Aberdeenshire",
- "province": "Aberdeenshire",
- "countryCode": "GB"
}, - "contactInformation": {
- "mobile": "string",
- "landline": "string",
- "fax": "string",
- "email": "string"
}, - "externalReference": {
- "providerCode": "PORSCHE",
- "applicationCode": "LEADMANAGEMENT",
- "value": "6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0"
}
}, - "vehicle": {
- "vehicleId": "4e00196a-5dee-e811-9112-005056983362",
- "make": "PORSCHE",
- "class": "CAR",
- "description": "Sport Saloon",
- "identification": {
- "vin": "1FTHF25H1JNB79097",
- "chassis": "68060",
- "licensePlate": "TOY-123",
- "engineNumber": "12345678"
}, - "referenceData": {
- "providerId": "string",
- "makeCode": "string",
- "modelCode": "string",
- "variantCode": "string",
- "vehicleCode": "string",
- "serviceGroupCode": "string",
- "exteriorColorCode": "string",
- "interiorColorCode": "string"
}, - "mileage": {
- "unit": "KM",
- "value": 120000
}
}, - "bookingOption": {
- "appointmentOptionId": "5000196a-5dee-e811-9112-005056983362",
- "customerNotes": "string",
- "collectAddress": {
- "streetType": "Avenue",
- "streetName": "Mill Lane",
- "houseNumber": "7",
- "buildingName": "Avance Hirise",
- "floorNumber": "3",
- "doorNumber": "12345",
- "blockName": "Block C",
- "estate": "Royal Estate",
- "postalCode": "SE4 1UU",
- "suburb": "Seafield",
- "city": "Glasgow",
- "county": "Aberdeenshire",
- "province": "Aberdeenshire",
- "countryCode": "GB"
}, - "deliveryAddress": {
- "streetType": "Avenue",
- "streetName": "Mill Lane",
- "houseNumber": "7",
- "buildingName": "Avance Hirise",
- "floorNumber": "3",
- "doorNumber": "12345",
- "blockName": "Block C",
- "estate": "Royal Estate",
- "postalCode": "SE4 1UU",
- "suburb": "Seafield",
- "city": "Glasgow",
- "county": "Aberdeenshire",
- "province": "Aberdeenshire",
- "countryCode": "GB"
}
}, - "serviceProducts": [
- {
- "serviceProductId": "5100196a-5dee-e811-9112-005056983362",
- "customerNotes": "string"
}
], - "additionalServiceProducts": [
- {
- "description": "Service product title",
- "customerNotes": "Customer note",
- "price": {
- "netValue": 100,
- "grossValue": 120,
- "taxValue": 20,
- "taxRate": 19.99,
- "currencyCode": "GBP"
}, - "indicativePrice": {
- "netValue": 100,
- "grossValue": 120,
- "taxValue": 20,
- "taxRate": 19.99,
- "currencyCode": "GBP"
}, - "menus": [
- {
- "sequenceNumber": 1,
- "description": "Main service",
- "menuCode": "SERVICE",
- "brandCode": "FORD",
- "laborItems": [
- {
- "sequenceNumber": 2,
- "description": "Oil check",
- "laborCode": "OILCHECK",
- "brandCode": "FORD",
- "allowedTimeInMinutes": 45
}
], - "partItems": [
- {
- "sequenceNumber": 3,
- "description": "CASTROL EDGE SPORT 5W-30",
- "partId": "ZZCASTROL-SW30",
- "partCode": "5010321000143",
- "brandCode": "FORD",
- "unitOfMeasure": "LITERS",
- "quantity": 2
}
], - "textItems": [
- {
- "sequenceNumber": 4,
- "notes": "Noice at the left front while breaking"
}
]
}
], - "laborItems": [
- {
- "sequenceNumber": 2,
- "description": "Oil check",
- "laborCode": "OILCHECK",
- "brandCode": "FORD",
- "allowedTimeInMinutes": 45
}
], - "partItems": [
- {
- "sequenceNumber": 3,
- "description": "CASTROL EDGE SPORT 5W-30",
- "partId": "ZZCASTROL-SW30",
- "partCode": "5010321000143",
- "brandCode": "FORD",
- "unitOfMeasure": "LITERS",
- "quantity": 2
}
], - "textItems": [
- {
- "sequenceNumber": 4,
- "notes": "Noice at the left front while breaking"
}
]
}
], - "metadata": {
- "auditData": {
- "userId": "123456",
- "userName": "Sam Service"
}
}
}
Response samples
- 201
- 202
- 409
{- "appointmentId": "5200196a-5dee-e811-9112-005056983362",
- "details": {
- "appointmentReference": "123455",
- "externalReference": "REF123",
- "customerNotes": "Please do not wash my car",
- "dueInDateTime": "2021-04-14T07:00:00.000Z",
- "dueOutDateTime": "2021-04-14T09:00:00.000Z",
- "contactAdvisor": {
- "advisorId": "SA12345",
- "name": "John Advise"
}
}, - "customer": {
- "customerId": "4e00196a-5dee-e811-9112-005056983362",
- "names": {
- "familyName": "string",
- "familyName2": "string",
- "middleName": "string",
- "givenName": "string",
- "preferredName": "string",
- "initials": "string",
- "salutation": "string",
- "titleCommon": "string"
}, - "address": {
- "streetType": "Avenue",
- "streetName": "Mill Lane",
- "houseNumber": "7",
- "buildingName": "Avance Hirise",
- "floorNumber": "3",
- "doorNumber": "12345",
- "blockName": "Block C",
- "estate": "Royal Estate",
- "postalCode": "SE4 1UU",
- "suburb": "Seafield",
- "city": "Glasgow",
- "county": "Aberdeenshire",
- "province": "Aberdeenshire",
- "countryCode": "GB"
}, - "contactInformation": {
- "mobile": "string",
- "landline": "string",
- "fax": "string",
- "email": "string"
}, - "externalReference": {
- "providerCode": "PORSCHE",
- "applicationCode": "LEADMANAGEMENT",
- "value": "6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0"
}
}, - "vehicle": {
- "vehicleId": "4e00196a-5dee-e811-9112-005056983362",
- "make": "PORSCHE",
- "class": "CAR",
- "description": "Sport Saloon",
- "identification": {
- "vin": "1FTHF25H1JNB79097",
- "chassis": "68060",
- "licensePlate": "TOY-123",
- "engineNumber": "12345678"
}, - "referenceData": {
- "providerId": "string",
- "makeCode": "string",
- "modelCode": "string",
- "variantCode": "string",
- "vehicleCode": "string",
- "serviceGroupCode": "string",
- "exteriorColorCode": "string",
- "interiorColorCode": "string"
}, - "mileage": {
- "unit": "KM",
- "value": 120000
}
}, - "bookingOption": {
- "appointmentOptionId": "5000196a-5dee-e811-9112-005056983362",
- "customerNotes": "string",
- "collectAddress": {
- "streetType": "Avenue",
- "streetName": "Mill Lane",
- "houseNumber": "7",
- "buildingName": "Avance Hirise",
- "floorNumber": "3",
- "doorNumber": "12345",
- "blockName": "Block C",
- "estate": "Royal Estate",
- "postalCode": "SE4 1UU",
- "suburb": "Seafield",
- "city": "Glasgow",
- "county": "Aberdeenshire",
- "province": "Aberdeenshire",
- "countryCode": "GB"
}, - "deliveryAddress": {
- "streetType": "Avenue",
- "streetName": "Mill Lane",
- "houseNumber": "7",
- "buildingName": "Avance Hirise",
- "floorNumber": "3",
- "doorNumber": "12345",
- "blockName": "Block C",
- "estate": "Royal Estate",
- "postalCode": "SE4 1UU",
- "suburb": "Seafield",
- "city": "Glasgow",
- "county": "Aberdeenshire",
- "province": "Aberdeenshire",
- "countryCode": "GB"
}
}, - "serviceProducts": [
- {
- "serviceProductId": "5100196a-5dee-e811-9112-005056983362",
- "customerNotes": "string"
}
], - "additionalServiceProducts": [
- {
- "description": "Service product title",
- "customerNotes": "Customer note",
- "price": {
- "netValue": 100,
- "grossValue": 120,
- "taxValue": 20,
- "taxRate": 19.99,
- "currencyCode": "GBP"
}, - "indicativePrice": {
- "netValue": 100,
- "grossValue": 120,
- "taxValue": 20,
- "taxRate": 19.99,
- "currencyCode": "GBP"
}, - "menus": [
- {
- "sequenceNumber": 1,
- "description": "Main service",
- "menuCode": "SERVICE",
- "brandCode": "FORD",
- "laborItems": [
- {
- "sequenceNumber": 2,
- "description": "Oil check",
- "laborCode": "OILCHECK",
- "brandCode": "FORD",
- "allowedTimeInMinutes": 45
}
], - "partItems": [
- {
- "sequenceNumber": 3,
- "description": "CASTROL EDGE SPORT 5W-30",
- "partId": "ZZCASTROL-SW30",
- "partCode": "5010321000143",
- "brandCode": "FORD",
- "unitOfMeasure": "LITERS",
- "quantity": 2
}
], - "textItems": [
- {
- "sequenceNumber": 4,
- "notes": "Noice at the left front while breaking"
}
]
}
], - "laborItems": [
- {
- "sequenceNumber": 2,
- "description": "Oil check",
- "laborCode": "OILCHECK",
- "brandCode": "FORD",
- "allowedTimeInMinutes": 45
}
], - "partItems": [
- {
- "sequenceNumber": 3,
- "description": "CASTROL EDGE SPORT 5W-30",
- "partId": "ZZCASTROL-SW30",
- "partCode": "5010321000143",
- "brandCode": "FORD",
- "unitOfMeasure": "LITERS",
- "quantity": 2
}
], - "textItems": [
- {
- "sequenceNumber": 4,
- "notes": "Noice at the left front while breaking"
}
]
}
]
}
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:
path Parameters
appointmentId required | string |
Responses
Response samples
- 200
- 403
- 404
{- "appointmentId": "5200196a-5dee-e811-9112-005056983362",
- "details": {
- "appointmentReference": "123455",
- "externalReference": "REF123",
- "dueInDateTime": "2021-04-14T07:00:00.000Z",
- "dueOutDateTime": "2021-04-14T09:00:00.000Z",
- "contactAdvisor": {
- "advisorId": "SA12345",
- "name": "John Advise"
}, - "repairOrder": {
- "repairOrderId": "00000000-0000-0000-0000-000000000000",
- "reference": "123456"
}
}, - "customer": {
- "customerId": "4e00196a-5dee-e811-9112-005056983362",
- "names": {
- "familyName": "string",
- "familyName2": "string",
- "middleName": "string",
- "givenName": "string",
- "preferredName": "string",
- "initials": "string",
- "salutation": "string",
- "titleCommon": "string"
}, - "address": {
- "streetType": "Avenue",
- "streetName": "Mill Lane",
- "houseNumber": "7",
- "buildingName": "Avance Hirise",
- "floorNumber": "3",
- "doorNumber": "12345",
- "blockName": "Block C",
- "estate": "Royal Estate",
- "postalCode": "SE4 1UU",
- "suburb": "Seafield",
- "city": "Glasgow",
- "county": "Aberdeenshire",
- "province": "Aberdeenshire",
- "countryCode": "GB"
}, - "contactInformation": {
- "mobile": "string",
- "landline": "string",
- "fax": "string",
- "email": "string"
}
}, - "vehicle": {
- "vehicleId": "4e00196a-5dee-e811-9112-005056983362",
- "make": "PORSCHE",
- "class": "CAR",
- "description": "Sport Saloon",
- "identification": {
- "vin": "1FTHF25H1JNB79097",
- "chassis": "68060",
- "licensePlate": "TOY-123",
- "engineNumber": "12345678"
}, - "mileage": {
- "unit": "KM",
- "value": 120000
}
}, - "bookingOption": {
- "transportationType": "NONE",
- "collectAddress": {
- "streetType": "Avenue",
- "streetName": "Mill Lane",
- "houseNumber": "7",
- "buildingName": "Avance Hirise",
- "floorNumber": "3",
- "doorNumber": "12345",
- "blockName": "Block C",
- "estate": "Royal Estate",
- "postalCode": "SE4 1UU",
- "suburb": "Seafield",
- "city": "Glasgow",
- "county": "Aberdeenshire",
- "province": "Aberdeenshire",
- "countryCode": "GB"
}, - "deliveryAddress": {
- "streetType": "Avenue",
- "streetName": "Mill Lane",
- "houseNumber": "7",
- "buildingName": "Avance Hirise",
- "floorNumber": "3",
- "doorNumber": "12345",
- "blockName": "Block C",
- "estate": "Royal Estate",
- "postalCode": "SE4 1UU",
- "suburb": "Seafield",
- "city": "Glasgow",
- "county": "Aberdeenshire",
- "province": "Aberdeenshire",
- "countryCode": "GB"
}
}
}
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:
path Parameters
appointmentId required | string |
Request Body schema: application/json
object Metadata for the action |
Responses
Request samples
- Payload
{- "metadata": {
- "auditData": {
- "userId": "123456",
- "userName": "Sam Service"
}
}
}
Response samples
- 403
- 404
{- "correlationId": "48fb4cd3-2ef6-4479-bea1-7c92721b988c",
- "message": "Invalid request",
- "details": [
- {
- "field": "Status",
- "value": "string",
- "issue": "The value 'XYZ' is not valid."
}
], - "links": [
- {
- "method": "GET",
- "rel": "self",
- "href": "string",
- "title": "string"
}
]
}
Find Appointment Options
Get the options for a given appointment using the appointment Id
Authorizations:
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
- 200
{- "totalItems": 4,
- "totalPages": 1,
- "appointmentOptions": [
- {
- "appointmentOptionId": "5100196a-5dee-e811-9112-005056983362",
- "description": "Customer waiting",
- "notes": "string",
- "transportationType": "NONE",
- "price": {
- "netValue": 100,
- "grossValue": 120,
- "taxValue": 20,
- "taxRate": 19.99,
- "currencyCode": "GBP"
}, - "indicativePrice": {
- "netValue": 100,
- "grossValue": 120,
- "taxValue": 20,
- "taxRate": 19.99,
- "currencyCode": "GBP"
}, - "vehicle": {
- "make": "string",
- "model": "string",
- "vehicleClass": "CAR",
- "fuelTypes": [
- {
- "fuelTypeId": "diesel",
- "fuelTypeName": "Diesel",
- "isActive": false
}
], - "electricVehicleTypes": [
- {
- "electricVehicleTypeId": "hev",
- "electricVehicleTypeName": "Hybrid Electric Vehicle (HEV)",
- "isActive": false
}
]
}
}
]
}
Get Appointment Option
Get details of option for an appointment using an appointmentOptionId
Authorizations:
path Parameters
appointmentOptionId required | string Appointment option unique ID |
Responses
Response samples
- 200
- 404
{- "appointmentOptionId": "5100196a-5dee-e811-9112-005056983362",
- "description": "Customer waiting",
- "notes": "string",
- "transportationType": "NONE",
- "price": {
- "netValue": 100,
- "grossValue": 120,
- "taxValue": 20,
- "taxRate": 19.99,
- "currencyCode": "GBP"
}, - "indicativePrice": {
- "netValue": 100,
- "grossValue": 120,
- "taxValue": 20,
- "taxRate": 19.99,
- "currencyCode": "GBP"
}, - "vehicle": {
- "make": "string",
- "model": "string",
- "vehicleClass": "CAR",
- "fuelTypes": [
- {
- "fuelTypeId": "diesel",
- "fuelTypeName": "Diesel",
- "isActive": false
}
], - "electricVehicleTypes": [
- {
- "electricVehicleTypeId": "hev",
- "electricVehicleTypeName": "Hybrid Electric Vehicle (HEV)",
- "isActive": false
}
]
}, - "links": [
- {
- "method": "GET",
- "rel": "self",
- "href": "string",
- "title": "string"
}
]
}
Find Service Products
Get the service products for an appointment
Authorizations:
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:
A non-zero integer representing the page of the results |
pageSize | integer >= 50 Default: 50 Examples:
A non-negative, non-zero integer indicating the maximum number of results to return at one time |
Responses
Response samples
- 200
{- "totalItems": 4,
- "totalPages": 1,
- "serviceProducts": [
- {
- "serviceProductId": "5100196a-5dee-e811-9112-005056983362",
- "vehicle": {
- "make": "string",
- "model": "string",
- "vehicleClass": "CAR",
- "fuelTypes": [
- {
- "fuelTypeId": "diesel",
- "fuelTypeName": "Diesel",
- "isActive": false
}
], - "electricVehicleTypes": [
- {
- "electricVehicleTypeId": "hev",
- "electricVehicleTypeName": "Hybrid Electric Vehicle (HEV)",
- "isActive": false
}
]
}, - "serviceCategory": {
- "code": "string",
- "description": "string"
}, - "description": "Full service plus",
- "notes": "string",
- "requiredTimeInMinutes": 45,
- "price": {
- "netValue": 100,
- "grossValue": 120,
- "taxValue": 20,
- "taxRate": 19.99,
- "currencyCode": "GBP"
}, - "indicativePrice": {
- "netValue": 100,
- "grossValue": 120,
- "taxValue": 20,
- "taxRate": 19.99,
- "currencyCode": "GBP"
}
}
], - "links": [
- {
- "method": "GET",
- "rel": "self",
- "href": "string",
- "title": "string"
}
]
}
Get Service Product
Get a service product using a serviceProductId
Authorizations:
path Parameters
serviceProductId required | string |
Responses
Response samples
- 200
- 404
{- "serviceProductId": "5100196a-5dee-e811-9112-005056983362",
- "vehicle": {
- "make": "string",
- "model": "string",
- "vehicleClass": "CAR",
- "fuelTypes": [
- {
- "fuelTypeId": "diesel",
- "fuelTypeName": "Diesel",
- "isActive": false
}
], - "electricVehicleTypes": [
- {
- "electricVehicleTypeId": "hev",
- "electricVehicleTypeName": "Hybrid Electric Vehicle (HEV)",
- "isActive": false
}
]
}, - "description": "string",
- "notes": "Full service plus",
- "serviceCategory": {
- "code": "string",
- "description": "string"
}, - "requiredTimeInMinutes": 45,
- "price": {
- "netValue": 100,
- "grossValue": 120,
- "taxValue": 20,
- "taxRate": 19.99,
- "currencyCode": "GBP"
}, - "indicativePrice": {
- "netValue": 100,
- "grossValue": 120,
- "taxValue": 20,
- "taxRate": 19.99,
- "currencyCode": "GBP"
}, - "advisorRequired": true,
- "links": [
- {
- "method": "GET",
- "rel": "self",
- "href": "string",
- "title": "string"
}
]
}