swagger: '2.0' info: version: 3.0.0 title: appointments adopt Service Booking API description: "## Fortellis - Service - Appointments\nA 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.\n\n## What does this API do?\nThe API will allow you to query, create and manage service appointments. \n\n## Intended Audience\nIt 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.\n" contact: name: Developer Evangelists url: https://example.com email: support@fortellis.io host: fortellis.io basePath: /sales/notification/v3 schemes: - https security: - permission-model: - anonymous tags: - name: Service Booking paths: /booking-sessions: post: summary: Create a bookingSession tags: - Service Booking produces: - application/json consumes: - application/json description: Creates a Booking Session. This session encapsulates the process of establishing the vehicle to be serviced, what services will be performed, what customer transportation is requested, and which available appointment slots are available. operationId: createBookingSession responses: '201': $ref: '#/responses/Created' '400': $ref: '#/responses/BadRequest' '403': $ref: '#/responses/Forbidden' parameters: - $ref: '#/parameters/header.Request-Id' - $ref: '#/parameters/header.Subscription-Id' - $ref: '#/parameters/header.Authorization' - $ref: '#/parameters/header.Content-Type' - $ref: '#/parameters/body.CreateBookingSessionPayload' /booking-sessions/{bookingSessionId}/items: post: produces: - application/json consumes: - application/json summary: Adds a requested service item to the Booking Session tags: - Service Booking description: Adds a requested service item to the Booking Session operationId: addBookingSessionItem responses: '201': $ref: '#/responses/Created' '400': $ref: '#/responses/BadRequest' parameters: - $ref: '#/parameters/header.Request-Id' - $ref: '#/parameters/header.Subscription-Id' - $ref: '#/parameters/header.Authorization' - $ref: '#/parameters/header.Content-Type' - $ref: '#/parameters/path.bookingSessionId' - $ref: '#/parameters/body.AddItemPayload' get: consumes: - application/json summary: Queries the service items of the Booking Session tags: - Service Booking description: Queries the requested service items of the Booking Session operationId: queryBookingSessionItems produces: - application/json parameters: - $ref: '#/parameters/header.Request-Id' - $ref: '#/parameters/header.Subscription-Id' - $ref: '#/parameters/header.Authorization' - $ref: '#/parameters/path.bookingSessionId' responses: '200': $ref: '#/responses/items' '400': $ref: '#/responses/BadRequest' '403': $ref: '#/responses/Forbidden' '404': $ref: '#/responses/NotFound' '410': $ref: '#/responses/Gone' /booking-sessions/{bookingSessionId}/items/{itemId}: post: produces: - application/json consumes: - application/json summary: Updates a requested service item to the Booking Session tags: - Service Booking description: Updates a requested service item to the Booking Session operationId: updateBookingSessionItem responses: '200': $ref: '#/responses/OK' '400': $ref: '#/responses/BadRequest' '403': $ref: '#/responses/Forbidden' '404': $ref: '#/responses/NotFound' parameters: - $ref: '#/parameters/header.Request-Id' - $ref: '#/parameters/header.Subscription-Id' - $ref: '#/parameters/header.Authorization' - $ref: '#/parameters/header.Content-Type' - $ref: '#/parameters/path.bookingSessionId' - $ref: '#/parameters/path.itemId' - $ref: '#/parameters/body.UpdateItemPayload' get: consumes: - application/json produces: - application/json summary: Queries a requested service item by identifier tags: - Service Booking description: Queries a requested service item by identifier operationId: queryRequestedServiceItemById responses: '200': $ref: '#/responses/items' '400': $ref: '#/responses/BadRequest' '403': $ref: '#/responses/Forbidden' '404': $ref: '#/responses/NotFound' '410': $ref: '#/responses/Gone' parameters: - $ref: '#/parameters/header.Request-Id' - $ref: '#/parameters/header.Subscription-Id' - $ref: '#/parameters/header.Authorization' - $ref: '#/parameters/path.bookingSessionId' - $ref: '#/parameters/path.itemId' delete: consumes: - application/json produces: - application/json summary: Removes a service item from the Booking Session tags: - Service Booking description: Removes a service item from the Booking Session operationId: removeBookingSessionItem responses: '200': $ref: '#/responses/OK' '400': $ref: '#/responses/BadRequest' '403': $ref: '#/responses/Forbidden' '404': $ref: '#/responses/NotFound' parameters: - $ref: '#/parameters/header.Request-Id' - $ref: '#/parameters/header.Subscription-Id' - $ref: '#/parameters/header.Authorization' - $ref: '#/parameters/header.Content-Type' - $ref: '#/parameters/path.bookingSessionId' - $ref: '#/parameters/path.itemId' /booking-sessions/{bookingSessionId}/available-stores: get: consumes: - application/json produces: - application/json summary: Queries the store availability for appointments for booking tags: - Service Booking description: Queries the store availability for appointments for booking operationId: queryBookingSessionStoreAvailability responses: '200': $ref: '#/responses/AvailableStore' '400': $ref: '#/responses/BadRequest' '403': $ref: '#/responses/Forbidden' '404': $ref: '#/responses/NotFound' '410': $ref: '#/responses/Gone' parameters: - $ref: '#/parameters/header.Request-Id' - $ref: '#/parameters/header.Subscription-Id' - $ref: '#/parameters/header.Authorization' - $ref: '#/parameters/path.bookingSessionId' /booking-sessions/{bookingSessionId}/available-stores/{storeId}/slots: get: consumes: - application/json produces: - application/json summary: Queries the available appointment slots by store tags: - Service Booking description: Queries the available appointment slots by store operationId: queryBookingSessionsAvailableStoreSlots responses: '200': $ref: '#/responses/Slot' '400': $ref: '#/responses/BadRequest' '403': $ref: '#/responses/Forbidden' '404': $ref: '#/responses/NotFound' '410': $ref: '#/responses/Gone' parameters: - $ref: '#/parameters/header.Request-Id' - $ref: '#/parameters/header.Subscription-Id' - $ref: '#/parameters/header.Authorization' - $ref: '#/parameters/path.bookingSessionId' - $ref: '#/parameters/path.storeId' /booking-sessions/{bookingSessionId}/available-stores/{storeId}/slots/{slotId}: get: consumes: - application/json produces: - application/json summary: Queries an available appointment slot tags: - Service Booking description: Queries an available appointment slot operationId: queryBookingSessionsAvailableSlot responses: '200': $ref: '#/responses/Slot' '400': $ref: '#/responses/BadRequest' '403': $ref: '#/responses/Forbidden' '404': $ref: '#/responses/NotFound' '410': $ref: '#/responses/Gone' parameters: - $ref: '#/parameters/header.Request-Id' - $ref: '#/parameters/header.Subscription-Id' - $ref: '#/parameters/header.Authorization' - $ref: '#/parameters/path.bookingSessionId' - $ref: '#/parameters/path.storeId' - $ref: '#/parameters/path.slotId' post: consumes: - application/json produces: - application/json summary: Books an appointment slot. This is the final step in the appointment booking process. tags: - Service Booking description: Books an appointment slot. This is the final step in the appointment booking process. operationId: bookAppointmentSlot responses: '201': $ref: '#/responses/Created' '400': $ref: '#/responses/BadRequest' '403': $ref: '#/responses/Forbidden' '404': $ref: '#/responses/NotFound' '410': $ref: '#/responses/Gone' parameters: - $ref: '#/parameters/header.Request-Id' - $ref: '#/parameters/header.Subscription-Id' - $ref: '#/parameters/header.Authorization' - $ref: '#/parameters/header.Content-Type' - $ref: '#/parameters/path.bookingSessionId' - $ref: '#/parameters/path.storeId' - $ref: '#/parameters/path.slotId' definitions: AddItemPayload: description: This describes the item that was added to the payload. required: - text - comment - id - specificationId properties: text: type: string description: A text field. comment: type: string description: A comment field. id: type: string description: The service package Id. Unique when coupled with vehicleSpecId specificationId: type: string description: The specific instance of the service package. example: text: Windshield Wiper Motor - Replace id: BY28 comment: Customer requested service. specificationId: '21732242' AvailableStore: description: This shows when the store has available slots. required: - storeId - slots - links properties: storeId: type: string format: uuid description: The identifier of the store slots: type: array items: $ref: '#/definitions/Slot' description: The available appointment slots links: $ref: '#/definitions/LinksObject' example: storeId: 01b1a2a6-257d-4b35-b4c2-ae08153033ca slots: - time - time - time links: bookingSessions: functions: Create a booking session. href: /booking-sessions methods: GET: false POST: true DELETE: false bookingSessionItems: functions: Create and query session items. href: /booking-sessions/{bookingSessionId}/items methods: GET: true POST: true DELETE: false bookingSessionItem: functions: Create and delete session items. href: /booking-sessions/{bookingSessionId}/items/{itemId} methods: GET: false POST: true DELETE: true bookingSessionAvailableStores: functions: Query the available stores. href: /booking-sessions/{bookingSessionId}/available-stores methods: GET: true POST: false DELETE: false bookingSessionAvailableStoreSlots: functions: Query slots that an available store has. href: /booking-sessions/{bookingSessionId}/available-stores/{storeId}/slots methods: GET: true POST: false DELETE: false bookingSessionAvailableStoreSlot: functions: Book and query a slot. href: /booking-sessions/{bookingSessionId}/available-stores/{storeId}/slots/{slotId} methods: GET: true POST: true DELETE: false CreateBookingSessionPayload: description: This is the booking session payload. required: - storeIdList - searchWindowStart - searchWindowEnd - links properties: vehicleSpecId: type: string description: The vehicle service model identifier vehicleTypeId: type: string format: uuid description: The identifier of the vehicle type customerId: type: string format: uuid description: The identifier of the customer storeIdList: type: array items: type: string format: uuid description: The identifiers of the stores to search searchWindowStart: type: string format: date-time description: The the start of the search window searchWindowEnd: type: string format: date-time description: The the end of the search window requestedTransportation: type: string enum: - WAITER - LOANER - RENTAL - VALET_PICKUP - SHUTTLE description: The requested customer transportation example: - appointmentId: 79667722-fcc4-4cd8-995b-75d566bbba1b storeId: 85254b70-c4b0-4461-937f-34d3502796bd vehicleSpecId: CHEV-CORVST-2017-US customerId: e3ad5443-72a7-4423-af2c-a5d7d510a39e advisorId: 282fc845-868d-4678-b06c-82a6794e6309 accommodation: accommodationId: fd133724-3450-47c3-b4a4-f888dbf74e40 accommodationRef: xchange.com/loaner-car/api/accommodation/v1 description: A courtesy loaner car has been reserved for Ms. Jones dateTime: '2019-10-11T09:32:04+00:00' status: BOOKED TransportationOption: description: This indicates the option of transportation that the customer selected. required: - transportationOptionId - description properties: transportationOptionId: type: string format: uuid description: The identifier of the transportation option description: type: string example: transportationOptionId: 779913c9-bb93-46f0-8860-9c893128c62c description: Some description Cost: description: This is the description of the cost. required: - baseCost - currencyType properties: baseCost: type: number description: The base cost currencyType: type: string description: The currency type of the cost example: baseCost: 53.42 currencyType: US TransportationOffer: description: This is the offer to provide transportation. required: - transportationOfferId - description - cost properties: transportationOfferId: type: string format: uuid description: The identifier of the transportation offer description: type: string description: The description transportation offer cost: $ref: '#/definitions/Cost' example: transportationOfferId: fd133724-3450-47c3-b4a4-f888dbf74e40 description: Midsized loaner car cost: baseCost: 0.0 currencyType: GBP Error: description: This is the description of the error that you are getting. required: - code - message properties: code: type: integer format: int32 message: type: string example: code: 400 message: Bad Request Ok: description: This describes a successful POST to update an item. required: - success - links properties: success: type: string links: $ref: '#/definitions/LinksObject' example: success: OK links: bookingSessions: functions: Create a booking session. href: /booking-sessions methods: GET: false POST: true DELETE: false bookingSessionItems: functions: Create and query session items. href: /booking-sessions/{bookingSessionId}/items methods: GET: true POST: true DELETE: false bookingSessionItem: functions: Create and delete session items. href: /booking-sessions/{bookingSessionId}/items/{itemId} methods: GET: false POST: true DELETE: true bookingSessionAvailableStores: functions: Query the available stores. href: /booking-sessions/{bookingSessionId}/available-stores methods: GET: true POST: false DELETE: false bookingSessionAvailableStoreSlots: functions: Query slots that an available store has. href: /booking-sessions/{bookingSessionId}/available-stores/{storeId}/slots methods: GET: true POST: false DELETE: false bookingSessionAvailableStoreSlot: functions: Book and query a slot. href: /booking-sessions/{bookingSessionId}/available-stores/{storeId}/slots/{slotId} methods: GET: true POST: true DELETE: false Slot: description: This field indicates the time slot that the store selects a time slot to offer the transportation. required: - slotId - storeId - dateTime - transportationOffer - links properties: slotId: type: string format: uuid description: The identifier of the slot storeId: type: string format: uuid description: The identifier of the store dateTime: type: string format: date-time description: The date and time of the slot transportationOffer: $ref: '#/definitions/TransportationOffer' links: $ref: '#/definitions/LinksObject' example: slotId: 85254b70-c4b0-4461-937f-34d3502796bd dateTime: '2019-10-11T09:30:00+00:00' storeId: 85254b70-c4b0-4461-937f-34d3502796bd transportationOffer: transportationOfferId: fd133724-3450-47c3-b4a4-f888dbf74e40 description: Midsized loaner car cost: baseCost: 0.0 currencyType: GBP links: bookingSessions: functions: Create a booking session. href: /booking-sessions methods: GET: false POST: true DELETE: false bookingSessionItems: functions: Create and query session items. href: /booking-sessions/{bookingSessionId}/items methods: GET: true POST: true DELETE: false bookingSessionItem: functions: Create and delete session items. href: /booking-sessions/{bookingSessionId}/items/{itemId} methods: GET: false POST: true DELETE: true bookingSessionAvailableStores: functions: Query the available stores. href: /booking-sessions/{bookingSessionId}/available-stores methods: GET: true POST: false DELETE: false bookingSessionAvailableStoreSlots: functions: Query slots that an available store has. href: /booking-sessions/{bookingSessionId}/available-stores/{storeId}/slots methods: GET: true POST: false DELETE: false bookingSessionAvailableStoreSlot: functions: Book and query a slot. href: /booking-sessions/{bookingSessionId}/available-stores/{storeId}/slots/{slotId} methods: GET: true POST: true DELETE: false BookingSession: description: This confirms the booking session when you have booked something. required: - bookingSessionId - storeIdList - vehicleSpecId - vehicleTypeId - customerId - searchWindowStart - searchWindowEnd - transportationOptions - selectedTransportationOptions - links properties: bookingSessionId: type: string description: The identifier of the booking session storeIdList: type: array items: type: string description: The identifiers of the stores to search vehicleSpecId: type: string description: The vehicle service model identifier vehicleTypeId: type: string description: The identifier of the vehicle type customerId: type: string description: The unique identifier of the customer searchWindowStart: type: string format: date-time description: The the start of the search window searchWindowEnd: type: string format: date-time description: The the end of the search window transportationOptions: type: array items: $ref: '#/definitions/TransportationOption' description: The available transportation options given the current filters selectedTransportationOptions: type: array items: type: string description: The identifiers of the selected available transportation options links: $ref: '#/definitions/LinksObject' example: bookingSessionId: 0fe1767a-0556-4661-9991-19dcfbb74421 storeIdList: - 29e1d17e-1ccf-4992-8ee0-e28dd75a3f75 vehicleSpecId: CHEV-CORVST-2017-US vehicleTypeId: d062d8d8-d2b4-4c28-8060-a2f6ed9c9257 customerId: 73589670-4891-4204-aa61-1ffe7ceea50e searchWindowStart: '2018-02-20T08:00:00Z' searchWindowEnd: '2018-02-21T16:00:00Z' transportationOptions: - transportationOptionId: 45e41b0d-099e-46d6-9ebd-ea35a2cd9f19 description: Customer waiting selectedTransportationOptions: - WAITER links: bookingSessions: functions: Create a booking session. href: /booking-sessions methods: GET: false POST: true DELETE: false bookingSessionItems: functions: Create and query session items. href: /booking-sessions/{bookingSessionId}/items methods: GET: true POST: true DELETE: false bookingSessionItem: functions: Create and delete session items. href: /booking-sessions/{bookingSessionId}/items/{itemId} methods: GET: false POST: true DELETE: true bookingSessionAvailableStores: functions: Query the available stores. href: /booking-sessions/{bookingSessionId}/available-stores methods: GET: true POST: false DELETE: false bookingSessionAvailableStoreSlots: functions: Query slots that an available store has. href: /booking-sessions/{bookingSessionId}/available-stores/{storeId}/slots methods: GET: true POST: false DELETE: false bookingSessionAvailableStoreSlot: functions: Book and query a slot. href: /booking-sessions/{bookingSessionId}/available-stores/{storeId}/slots/{slotId} methods: GET: true POST: true DELETE: false Item: description: This give the service package that the store would like to offer to the consumer. required: - itemId - text - comment - id - specificationId - links properties: itemId: type: string description: The unique identifier of the item text: type: string description: A text field. comment: type: string description: A comment field. id: type: string description: The service package Id. Unique when coupled with vehicleSpecId specificationId: type: string description: The specific instance of the service package. links: $ref: '#/definitions/LinksObject' example: itemId: f74d81c1-fe33-4f1a-a5f6-ace24da670a8 text: 30,000 mile service - 2014 Toyota Camry id: BY28 comment: Customer requested service. specificationId: '21732242' links: bookingSessions: functions: Create a booking session. href: /booking-sessions methods: GET: false POST: true DELETE: false bookingSessionItems: functions: Create and query session items. href: /booking-sessions/{bookingSessionId}/items methods: GET: true POST: true DELETE: false bookingSessionItem: functions: Create and delete session items. href: /booking-sessions/{bookingSessionId}/items/{itemId} methods: GET: false POST: true DELETE: true bookingSessionAvailableStores: functions: Query the available stores. href: /booking-sessions/{bookingSessionId}/available-stores methods: GET: true POST: false DELETE: false bookingSessionAvailableStoreSlots: functions: Query slots that an available store has. href: /booking-sessions/{bookingSessionId}/available-stores/{storeId}/slots methods: GET: true POST: false DELETE: false bookingSessionAvailableStoreSlot: functions: Book and query a slot. href: /booking-sessions/{bookingSessionId}/available-stores/{storeId}/slots/{slotId} methods: GET: true POST: true DELETE: false LinksObject: description: This is the common links object across all API calls. type: object properties: bookingSessions: type: object properties: functions: type: string href: type: string methods: type: object properties: POST: type: boolean GET: type: boolean DELETE: type: boolean bookingSessionItems: type: object properties: functions: type: string href: type: string methods: type: object properties: POST: type: boolean GET: type: boolean DELETE: type: boolean bookingSessionItem: type: object properties: functions: type: string href: type: string methods: type: object properties: POST: type: boolean GET: type: boolean DELETE: type: boolean bookingSessionAvailableStores: type: object properties: functions: type: string href: type: string methods: type: object properties: POST: type: boolean GET: type: boolean DELETE: type: boolean bookingSessionAvailableStoreSlots: type: object properties: functions: type: string href: type: string methods: type: object properties: POST: type: boolean GET: type: boolean DELETE: type: boolean bookingSessionAvailableStoreSlot: type: object properties: functions: type: string href: type: string methods: type: object properties: POST: type: boolean GET: type: boolean DELETE: type: boolean required: - bookingSessions - bookingSessionItems - bookingSessionItem - bookingSessionAvailableStores - bookingSessionAvailableStoreSlots - bookingSessionAvailableStoreSlot example: bookingSessions: functions: Create a booking session. href: /booking-sessions methods: GET: false POST: true DELETE: false bookingSessionItems: functions: Create and query session items. href: /booking-sessions/{bookingSessionId}/items methods: GET: true POST: true DELETE: false bookingSessionItem: functions: Create and delete session items. href: /booking-sessions/{bookingSessionId}/items/{itemId} methods: GET: false POST: true DELETE: true bookingSessionAvailableStores: functions: Query the available stores. href: /booking-sessions/{bookingSessionId}/available-stores methods: GET: true POST: false DELETE: false bookingSessionAvailableStoreSlots: functions: Query slots that an available store has. href: /booking-sessions/{bookingSessionId}/available-stores/{storeId}/slots methods: GET: true POST: false DELETE: false bookingSessionAvailableStoreSlot: functions: Book and query a slot. href: /booking-sessions/{bookingSessionId}/available-stores/{storeId}/slots/{slotId} methods: GET: true POST: true DELETE: false parameters: path.itemId: name: itemId in: path description: The identifier of the item required: true type: string 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. path.storeId: name: storeId in: path type: string format: uuid description: The store identifier => 000001 required: true body.UpdateItemPayload: name: UpdateItemPayload in: body description: The item update parameters schema: $ref: '#/definitions/AddItemPayload' 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.Request-Id: name: Request-Id required: true type: string in: header description: A correlation ID that should be returned back to the caller to indicate the return of the given request body.AddItemPayload: name: AddItemPayload in: body description: The requested bookingSession schema: $ref: '#/definitions/AddItemPayload' body.CreateBookingSessionPayload: name: CreateBookingSessionPayload in: body description: The bookingSession parameters. schema: $ref: '#/definitions/CreateBookingSessionPayload' path.bookingSessionId: name: bookingSessionId in: path description: The identifier of the bookingSession required: true type: string header.Content-Type: description: This field shows the content type that the client sent. name: Content-Type in: header required: true type: string enum: - application/json path.slotId: name: slotId in: path type: string format: uuid description: The slot identifier required: true responses: items: description: OK schema: $ref: '#/definitions/Item' Slot: description: OK - Slots schema: type: array items: $ref: '#/definitions/Slot' Forbidden: description: 403 - Forbidden headers: Request-Id: type: string schema: $ref: '#/definitions/Error' BadRequest: description: 400 - Bad Request headers: Request-Id: type: string schema: $ref: '#/definitions/Error' Gone: description: Gone schema: $ref: '#/definitions/Error' AvailableStore: description: Okay - Available Store schema: type: array items: $ref: '#/definitions/AvailableStore' OK: description: OK schema: $ref: '#/definitions/Ok' NotFound: description: 404 - Not Found headers: Request-Id: type: string schema: $ref: '#/definitions/Error' Created: description: Created. schema: $ref: '#/definitions/BookingSession' securityDefinitions: permission-model: type: oauth2 flow: implicit authorizationUrl: https://identity.fortellis.io/oauth2/ scopes: anonymous: Create, Query, Update, and Delete appointments