Fortellis Service Appointments API

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: [email protected]
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