Service-appointments API for booking, querying, updating, and cancelling vehicle service appointments at a dealership service department. Used by scheduling systems integrating with CDK and other DMS providers via Fortellis.
swagger: '2.0'
info:
version: '3.0.0'
title: appointments
description: |
## Fortellis - Service - Appointments
A service appointment is a booking of a vehicle into the service department for work that needs to be carried out on the vehicle. This could be a service, repair, body repair, government test etc.
## What does this API do?
The API will allow you to query, create and manage service appointments.
## Intended Audience
It is expected that systems that require create, read, update, and delete access to appointments will use this API. Systems implementing service-scheduling will use this API to store appointment records.
contact:
name: Developer Evangelists
url: https://example.com
email: support@fortellis.io
securityDefinitions:
permission-model:
type: oauth2
flow: implicit
authorizationUrl: https://identity.fortellis.io/oauth2/
scopes:
anonymous: Create, Query, Update, and Delete appointments
security:
- permission-model:
- 'anonymous'
host: fortellis.io
basePath: /sales/notification/v3
schemes:
- https
tags:
- Testing Tag
paths:
/:
get:
consumes:
- application/json
summary: Query appointments
description: Query appointments
operationId: queryAppointments
tags:
- query
parameters:
- $ref: '#/parameters/header.Accept'
- $ref: '#/parameters/header.Accept-Charset'
- $ref: '#/parameters/header.Accept-Language'
- $ref: '#/parameters/header.If-Match'
- $ref: '#/parameters/header.If-None-Match'
- $ref: '#/parameters/header.Prefer'
- $ref: '#/parameters/header.Request-Id'
- $ref: '#/parameters/header.Subscription-Id'
- $ref: '#/parameters/header.Authorization'
- $ref: '#/parameters/query.dateTimeInterval'
- $ref: '#/parameters/query.vehicleHref'
- $ref: '#/parameters/query.customerHref'
- $ref: '#/parameters/query.advisorHref'
produces:
- application/json
responses:
'200':
$ref: '#/responses/AppointmentCollection'
'400':
$ref: '#/responses/BadRequest'
'401':
$ref: '#/responses/Unauthorized'
'403':
$ref: '#/responses/Forbidden'
post:
consumes:
- application/json
summary: Create an appointment
description: |
Creates an appointment. Creating an appointment using this endpoint does not require the underlying system to implement any appointment capacity checks or dependent resource reservations. It is suggested that the service-scheduling API be used for this purpose.
operationId: createAppointment
tags:
- create
parameters:
- $ref: '#/parameters/header.Accept'
- $ref: '#/parameters/header.Accept-Charset'
- $ref: '#/parameters/header.Accept-Language'
- $ref: '#/parameters/header.If-Match'
- $ref: '#/parameters/header.If-None-Match'
- $ref: '#/parameters/header.Prefer'
- $ref: '#/parameters/header.Request-Id'
- $ref: '#/parameters/header.Subscription-Id'
- $ref: '#/parameters/header.Authorization'
- $ref: '#/parameters/body.CreateRequest'
produces:
- application/json
responses:
'200':
$ref: '#/responses/Appointment'
'400':
$ref: '#/responses/BadRequest'
'401':
$ref: '#/responses/Unauthorized'
'403':
$ref: '#/responses/Forbidden'
/{appointmentId}:
get:
consumes:
- application/json
summary: Query an appointment
description: Query an appointment
operationId: queryAppointment
tags:
- query
parameters:
- $ref: '#/parameters/header.Accept'
- $ref: '#/parameters/header.Accept-Charset'
- $ref: '#/parameters/header.Accept-Language'
- $ref: '#/parameters/header.If-Match'
- $ref: '#/parameters/header.If-None-Match'
- $ref: '#/parameters/header.Prefer'
- $ref: '#/parameters/header.Request-Id'
- $ref: '#/parameters/header.Subscription-Id'
- $ref: '#/parameters/header.Authorization'
- $ref: '#/parameters/path.appointmentId'
produces:
- application/json
responses:
'200':
$ref: '#/responses/Appointment'
'400':
$ref: '#/responses/BadRequest'
'401':
$ref: '#/responses/Unauthorized'
'403':
$ref: '#/responses/Forbidden'
'404':
$ref: '#/responses/NotFound'
post:
consumes:
- application/json
summary: Update an appointment
description: |
Update an appointment. This method does not guarantee that resource reservations associated with the appointment (advisors, transports, reserved equipment/parts) will be updated. It is suggested that the service-scheduling API be used for this purpose.
operationId: updateAppointment
tags:
- update
parameters:
- $ref: '#/parameters/header.Accept'
- $ref: '#/parameters/header.Accept-Charset'
- $ref: '#/parameters/header.Accept-Language'
- $ref: '#/parameters/header.If-Match'
- $ref: '#/parameters/header.If-None-Match'
- $ref: '#/parameters/header.Prefer'
- $ref: '#/parameters/header.Request-Id'
- $ref: '#/parameters/header.Subscription-Id'
- $ref: '#/parameters/header.Authorization'
- $ref: '#/parameters/path.appointmentId'
- $ref: '#/parameters/body.UpdateRequest'
produces:
- application/json
responses:
'200':
$ref: '#/responses/Appointment'
'400':
$ref: '#/responses/BadRequest'
'401':
$ref: '#/responses/Unauthorized'
'403':
$ref: '#/responses/Forbidden'
'404':
$ref: '#/responses/NotFound'
delete:
consumes:
- application/json
summary: Cancel an appointment
description: |
Cancels an appointment. This method does not guarantee that resource reservations associated with the appointment (advisors, transports, reserved equipment/parts) will be released. It is suggested that the service-scheduling API be used for this purpose.
operationId: cancelAppointment
tags:
- cancel
parameters:
- $ref: '#/parameters/header.Accept'
- $ref: '#/parameters/header.Accept-Charset'
- $ref: '#/parameters/header.Accept-Language'
- $ref: '#/parameters/header.If-Match'
- $ref: '#/parameters/header.If-None-Match'
- $ref: '#/parameters/header.Prefer'
- $ref: '#/parameters/header.Request-Id'
- $ref: '#/parameters/header.Subscription-Id'
- $ref: '#/parameters/header.Authorization'
- $ref: '#/parameters/path.appointmentId'
- $ref: '#/parameters/body.CancelRequest'
produces:
- application/json
responses:
'204':
$ref: '#/responses/Success'
'400':
$ref: '#/responses/BadRequest'
'401':
$ref: '#/responses/Unauthorized'
'403':
$ref: '#/responses/Forbidden'
'404':
$ref: '#/responses/NotFound'
parameters:
path.appointmentId:
name: appointmentId
in: path
required: true
type: string
description: The appointment identifier
body.CreateRequest:
name: CreateRequest
in: body
required: true
description: The definition of the appointment
schema:
$ref: '#/definitions/Appointment'
body.UpdateRequest:
name: UpdateRequest
in: body
required: true
description: The the defintion of the appointment update
schema:
$ref: '#/definitions/Appointment'
body.CancelRequest:
name: CancelRequest
in: body
required: true
description: An appointment cancellation request
schema:
$ref: '#/definitions/CancelRequest'
query.dateTimeInterval:
name: dateTimeInterval
in: query
required: false
type: string
description: The ISO 8601 data and time interval to filter the appointment query
query.vehicleHref:
name: vehicleHref
in: query
required: false
type: string
description: The vehicle resource hyperlink to filter query results
query.customerHref:
name: customerHref
in: query
required: false
type: string
description: The customer resource hyperlink to filter query results
query.advisorHref:
name: advisorHref
in: query
required: false
type: string
description: The advisor resource hyperlink to filter query results
# Common Parameters (see common.yaml)
header.Accept:
description: This header describes the characters that the API will accept.
name: Accept
in: header
type: string
enum:
- application/json
header.Accept-Charset:
description: This header describes the characters that the client will accept.
name: Accept-Charset
in: header
type: string
enum:
- utf-8
header.Accept-Language:
description: This header describes the languages that the client accepts.
name: Accept-Language
in: header
type: string
header.Prefer:
description: This header describes the preferences of the client calling the API.
name: Prefer
in: header
type: string
enum:
- return=representation
- return=minimal
header.If-Match:
name: If-Match
in: header
type: string
description: Specifies a conditional request to only return the resource when it does match one of the included ETag values
header.If-None-Match:
name: If-None-Match
in: header
type: string
description: Specifies a conditional request to only return the resource when it doesn't match one of the included ETag values
header.Request-Id:
name: Request-Id
in: header
required: true
type: string
format: guid
description: You must include the Request-Id in every call to track the same call across systems.
header.Subscription-Id:
name: Subscription-Id
in: header
required: true
type: string
format: guid
description: The Fortellis Marketplace subscription identifier between a user entity and the solution. For sample responses use the Subscription-Id 'test'.
header.Authorization:
name: Authorization
in: header
required: true
type: string
format: guid
description: Provides authorization to access Fortellis APIs. For calling a Fortellis Provider, this must be an OAuth 2.0 token issued by the Fortellis authorization server, but you may call the simulator platform with Basic Authorization using your API key and secret.
query.page:
name: page
in: query
description: A non-zero integer indicating the requested the page of query results
type: number
query.pageSize:
name: pageSize
in: query
description: A non-negative, non-zero integer indicating the maximum number of results to return at one time
type: number
responses:
AppointmentCollection:
description: OK
headers:
Request-Id:
type: string
schema:
$ref: '#/definitions/AppointmentCollection'
Appointment:
description: OK
headers:
Request-Id:
type: string
Preference-Applied:
type: string
enum:
- return=representation
- return=minimal
schema:
$ref: '#/definitions/AppointmentResource'
CreateAppointment:
description: Created
headers:
Request-Id:
type: string
Preference-Applied:
type: string
enum:
- return=representation
- return=minimal
schema:
$ref: '#/definitions/AppointmentResource'
# Common Responses (see common.yaml)
Success:
description: 204 - Non Content
headers:
Content-Language:
type: string
Content-Type:
type: string
Request-Id:
type: string
BadRequest:
description: 400 - Bad Request
headers:
Content-Language:
type: string
Content-Type:
type: string
Request-Id:
type: string
schema:
$ref: '#/definitions/ErrorResponse'
Unauthorized:
description: 401 - Unauthorized
headers:
Content-Language:
type: string
Content-Type:
type: string
Request-Id:
type: string
schema:
$ref: '#/definitions/ErrorResponse'
Forbidden:
description: 403 - Forbidden
headers:
Content-Language:
type: string
Content-Type:
type: string
Request-Id:
type: string
schema:
$ref: '#/definitions/ErrorResponse'
NotFound:
description: 404 - Not Found
headers:
Content-Language:
type: string
Content-Type:
type: string
Request-Id:
type: string
schema:
$ref: '#/definitions/ErrorResponse'
definitions:
Appointment:
description: This definition defines the information and format in appointments.
properties:
dateTime:
type: string
description: The ISO 8601 encode date and time of the appointment
requestedServices:
type: array
items:
$ref: '#/definitions/RequestedService'
description: The requested services to be performed on the vehicle
vehicleHref:
type: string
description: The hyperlink to the Vehicle resource scheduled for the appointment.
vehicleSpec:
$ref: '#/definitions/VehicleSpecification'
description: The make, model, and year describing the vehicle to be serviced. This must be provided if the 'vehicleHref' property is not specified.
vehicleMileage:
$ref: '#/definitions/Measurement'
description: The estimated mileage of the vehicle
customerHref:
type: string
description: The hyperlink to the customer who is requesting the vehicle service
contact:
$ref: '#/definitions/ContactMethod'
description: |
A contact method for the customer. This takes precedence over contact
methods present in the source customer record. This must be provided
if a customer resource link is not included.
transportHref:
type: string
description: The hyperlink to the requested transport
advisorHref:
type: string
description: The hyperlink to the requested service advisor
teamHref:
type: string
description: The hyperlink to the requested service team
concerns:
type: string
description: Concerns of the customer that prompted the appointment
remarks:
type: string
description: Comments by the service department staff about the appointment
required:
- dateTime
- requestedServices
example:
dateTime: '2019-06-10T16:15:00+08:00'
requestedServices:
- description: 'Filler, Tail Lamp Center - Replace (Labor Only)'
sourceHref: 'api.fortellis.io/service/reference/v4/service-packages/model/CHEV-CAMAC-2001-US/packages/BF018/specifications/8994972'
vehicleHref: 'api.fortellis.io/service/v1/vehicles/123'
vehicleMileage:
value: 34760
units: 'MILES'
customerHref: 'api.fortellis.io/service/v1/customers/123'
contact:
label: 'mobile'
uri: 'tel:1-234-567-8900'
preferences:
items:
startDay:
- MON
endDay:
- SAT
startTime: "1985-04-12T23:20:50.52Z"
endTime: "1985-04-18T23:20:50.52Z"
timezone: CST
transportHref: 'api.fortellis.io/service/v1/scheduling/lookups/transports/123'
advisorHref: 'api.fortellis.io/service/v1/scheduling/lookups/advisors/123'
concerns: 'My driver side front door rattles when I drive faster than 45'
remarks: 'Customer reports that driver side front door exhibits a rattle above 45mph'
RequestedService:
description: This fields describes the service requested.
type: object
properties:
description:
type: string
description: The textual description of the requested service
concern:
type: string
description: The textual description of the concern that prompted the requested service
sourceHref:
type: string
description: |
The hypermedia link to the source service specification. This will
link to a service-packages Specification or LaborOperation resource.
overrides:
type: object
properties:
quote:
$ref: '#/definitions/Price'
required:
- description
example:
description: 'Replace Air Filter'
sourceHref: 'api.fortellis.io/service/reference/v4/service-packages/model/CHEV-CAMAC-2001-US/packages/BF018/specifications/8994972'
# Resources
AppointmentResource:
description: This field describes the appointment resources.
allOf:
- $ref: '#/definitions/Appointment'
- type: object
properties:
appointmentId:
type: string
description: The appointment unique identifier
links:
$ref: '#/definitions/AppointmentLinks'
description: The hypermedia links of the Appointment resource
required:
- appointmentId
- links
example:
appointmentId: '123'
dateTime: '2019-06-10T16:15:00+08:00'
requestedServices:
- description: 'Filler, Tail Lamp Center - Replace (Labor Only)'
sourceHref: 'api.fortellis.io/service/reference/v4/service-packages/model/CHEV-CAMAC-2001-US/packages/BF018/specifications/8994972'
vehicleHref: 'api.fortellis.io/service/v1/vehicles/123'
vehicleMileage:
value: 34760
units: 'MILES'
customerHref: 'api.fortellis.io/service/v1/customers/123'
contact:
label: 'mobile'
uri: 'tel:1-234-567-8900'
preferences:
items:
startDay:
- MON
endDay:
- SAT
startTime: "1985-04-12T23:20:50.52Z"
endTime: "1985-04-18T23:20:50.52Z"
timezone: CST
transportHref: 'api.fortellis.io/service/v1/scheduling/lookups/transports/123'
advisorHref: 'api.fortellis.io/service/v1/scheduling/lookups/advisors/123'
concerns: 'My driver side front door rattles when I drive faster than 45'
remarks: 'Customer reports that driver side front door exhibits a rattle above 45mph'
links:
self:
href: 'api.fortellis.io/service/v3/appointments/123'
AppointmentLinks:
description: This field describes the appointment links.
type: object
properties:
self:
$ref: '#/definitions/LinkDescriptionObject'
description: The canonical link to the appointment resource
required:
- self
example:
self:
href: 'api.fortellis.io/service/v3/appointments/123'
# Requests
CancelRequest:
description: This fields describes why a customer requested to cancel.
type: object
properties:
reason:
type: string
description: Free-form comments that explain why the appointment was cancelled
required:
- reason
example:
reason: 'Rescheduled for the following week'
# Collections
AppointmentCollection:
description: This field describes a collection of appointments.
type: object
allOf:
- $ref: '#/definitions/BaseCollection'
- properties:
items:
type: object
items:
$ref: '#/definitions/Appointment'
required:
- items
required:
- items
example:
items:
appointmentId: '123'
dateTime: '2019-06-10T16:15:00+08:00'
requestedServices:
- description: 'Filler, Tail Lamp Center - Replace (Labor Only)'
sourceHref: 'api.fortellis.io/service/reference/v4/service-packages/model/CHEV-CAMAC-2001-US/packages/BF018/specifications/8994972'
vehicleHref: 'api.fortellis.io/service/v1/vehicles/123'
vehicleMileage:
value: 75201
units: 'MILES'
customerHref: 'api.fortellis.io/service/v1/customers/123'
contact:
label: 'mobile'
uri: 'tel:1-234-567-8900'
preferences:
- startDay: 'MON'
endDay: 'FRI'
startTime: '1000'
endTime: '1600'
transportHref: 'api.fortellis.io/service/v1/scheduling/lookups/transports/123'
advisorHref: 'api.fortellis.io/service/v1/scheduling/lookups/advisors/123'
concerns: 'My driver side front door rattles when I drive faster than 45'
remarks: 'Customer reports that driver side front door exhibits a rattle above 45mph'
links:
self:
href: 'api.fortellis.io/service/v3/appointments/123'
totalItems: 1
totalPages: 1
links:
first:
href: 'api.fortellis.io/service/v3/appointments?page=1&pageSize=1'
# Common Definitions (see common.yaml)
VehicleSpecification:
description: This field describes the vehicle.
type: object
properties:
makeCode:
type: string
description: The make code of the vehicle
modelCode:
type: string
description: The model code of the vehicle
modelYear:
type: number
description: The model year of the vehicle
required:
- makeCode
- modelCode
- modelYear
example:
makeCode: CHEV
modelCode: CAMAC
modelYear: 2001
Price:
description: This field lists the cost of the appointment.
type: object
properties:
currencyCode:
type: string
description: The ISO 4217 three letter currency code of the price
netPrice:
type: number
description: Price excluding sales tax / VAT expressed in the given currency
grossValue:
type: number
description: Price including sales tax / VAT expressed in the given currency
taxValue:
type: number
description: Value of tax expressed in the given currency
taxRate:
type: number
description: Tax rate as a percentage
netDiscountedPrice:
type: number
description: Discounted price exluding sales tax in the given currency
grossDiscountedPrice:
type: number
description: Discounted price including sales tax in the given currency
required:
- currencyCode
- netPrice
- grossValue
- taxValue
- taxRate
example:
currencyCode: US
netPrice: 53
grossValue: 57.24
taxValue: 4.24
taxRate: 8
Measurement:
description: This field will let you know about the value and the units of measurement.
type: object
required:
- units
- value
properties:
value:
type: number
units:
type: string
enum:
- MILES
- KM
- HOURS
example:
value: 75201
units: 'MILES'
BaseCollection:
description: This field describes the base collection.
type: object
properties:
totalItems:
type: number
description: The total number of items contained in the collection
totalPages:
type: number
description: The total number of pages given the requested page size
links:
$ref: '#/definitions/BaseCollectionLinks'
required:
- totalItems
- totalPages
- links
example:
totalItems: 16
totalPages: 4
links:
first:
href: https://example.com/first
rel: first
method: POST
title: First page
next:
href: https://example.com/next
rel: next
method: POST
title: Next page
prev:
href: https://example.com/prev
rel: prev
method: POST
title: Previous page
BaseCollectionLinks:
description: This field describes the base collection links for the particular endpoint.
type: object
properties:
next:
$ref: '#/definitions/LinkDescriptionObject'
description: The next page of query results
prev:
$ref: '#/definitions/LinkDescriptionObject'
description: The previous page of query results
first:
$ref: '#/definitions/LinkDescriptionObject'
description: The first page of query results
required:
- first
example:
next:
href: https://example.com/next
rel: next
method: POST
title: Next page
prev:
href: https://example.com/prev
rel: prev
method: POST
title: Previous page
first:
href: https://example.com/first
rel: first
method: POST
title: First page
ContactMethod:
description: This is the method that the customer would like you to use to contact them.
type: object
properties:
label:
type: string
description: A label used to describe the contact method (e.g. home, work-cell).
uri:
type: string
description: The RFC 3986 encoded URI address of the contact method.
preferences:
type: object
items:
$ref: '#/definitions/ContactPreference'
required:
- label
- uri
example:
label: Home Information
uri: https://examle.com/person/contact
preferences:
items:
startDay:
- MON
endDay:
- SAT
startTime: "1985-04-12T23:20:50.52Z"
endTime: "1985-04-18T23:20:50.52Z"
timezone: CST
ContactPreference:
description: This fields shows the customer's contact preferences.
type: object
required:
- startDay
- endDay
properties:
startDay:
type: string
enum:
- MON
- TUE
- WED
- THU
- FRI
- SAT
- SUN
description: The starting day of the interval
endDay:
type: string
enum:
- MON
- TUE
- WED
- THU
- FRI
- SAT
- SUN
description: The ending day of the interval
startTime:
type: string
description: The RFC 3339 encoded starting time of the interval
endTime:
type: string
description: The RFC 3339 encoded ending time of the interval
timeZone:
type: string
description: The IANA Timezone Database encoded timezone code of the interval
example:
startDay: MON
endDay: SAT
startTime: "1985-04-12T23:20:50.52Z"
endTime: "1985-04-18T23:20:50.52Z"
timezone: CST
LinkDescriptionObject:
description: These are the linked objects that you send with the request to comply with HATEOAS.
type: object
properties:
href:
type: string
description: The target URI
rel:
type: string
description: The link relation type
method:
type: string
description: The HTTP verb that MUST be used to make a request to the target of the link
title:
type: string
description: A human readable title for the link that conveys the purpose of the link
required:
- href
example:
href: https://example.com
rel: self
method: POST
title: Reference to self at the Example
ErrorResponse:
description: This is a generic error schema.
type: object
properties:
code:
type: integer
format: int32
message:
type: string
required:
- code
- message
example:
code: 24
message: Error Message used for debugging