Fleetkeep Bookings API

openapi: 3.2.0
info:
  title: Fleetkeep Co Uk Bookings API
  version: 0.8.0
  contact:
    name: Fleetkeep partner integration
    url: https://fleetkeep.co.uk/contact
    email: hello@fleetkeep.co.uk
  license:
    name: Proprietary
    url: https://fleetkeep.co.uk/legal/terms
  description: 'Operations tagged Bookings across 2 of this provider''s published API definitions: openapi.json, fleetkeep-co-uk-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://fleetkeep.co.uk
  description: Production
security:
- oauth2:
  - vehicles:read
tags:
- name: Bookings
  description: Save maintenance-derived booking requests. Garage email is a separate confirmed action.
paths:
  /api/v1/bookings:
    get:
      tags:
      - Bookings
      operationId: listBookings
      security:
      - oauth2:
        - maintenance:read
      responses:
        '200':
          description: Bookings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingList'
      summary: List bookings
      x-summary-source: derived
    post:
      tags:
      - Bookings
      operationId: createBooking
      description: Derives task, vehicle and category from an owned open maintenance event. It does not send email.
      security:
      - oauth2:
        - maintenance:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookingWrite'
      responses:
        '200':
          description: Idempotent replay of the saved booking
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingEnvelope'
        '201':
          description: Saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingEnvelope'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/ConfirmationConflict'
      summary: Create booking
      x-summary-source: derived
    servers:
    - url: https://fleetkeep.co.uk
      description: Production
  /api/v1/bookings/{id}:
    get:
      tags:
      - Bookings
      operationId: getBooking
      security:
      - oauth2:
        - maintenance:read
      parameters:
      - $ref: '#/components/parameters/BookingId'
      responses:
        '200':
          description: Booking
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingEnvelope'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/ConfirmationConflict'
      summary: Get booking
      x-summary-source: derived
    patch:
      tags:
      - Bookings
      operationId: updateBookingStatus
      security:
      - oauth2:
        - maintenance:write
      parameters:
      - $ref: '#/components/parameters/BookingId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookingStatusWrite'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingStatusEnvelope'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/ConfirmationConflict'
      summary: Update booking status
      x-summary-source: derived
    servers:
    - url: https://fleetkeep.co.uk
      description: Production
  /api/v1/bookings/{id}/garage-email/preview:
    post:
      tags:
      - Bookings
      operationId: previewGarageEmail
      security:
      - oauth2:
        - maintenance:write
      parameters:
      - $ref: '#/components/parameters/BookingId'
      responses:
        '200':
          description: Five-minute confirmation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundPreview'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/ConfirmationConflict'
      summary: Preview garage email
      x-summary-source: derived
    servers:
    - url: https://fleetkeep.co.uk
      description: Production
  /api/v1/bookings/{id}/garage-email/send:
    post:
      tags:
      - Bookings
      operationId: sendGarageEmail
      security:
      - oauth2:
        - maintenance:write
      parameters:
      - $ref: '#/components/parameters/BookingId'
      - $ref: '#/components/parameters/ActionConfirmation'
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Sent or replayed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/ConfirmationConflict'
        '502':
          $ref: '#/components/responses/ProviderFailure'
      summary: Send garage email
      x-summary-source: derived
    servers:
    - url: https://fleetkeep.co.uk
      description: Production
components:
  schemas:
    Error:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error:
          type: string
          example: registration_required
    BookingEnvelope:
      type: object
      additionalProperties: false
      required:
      - booking
      properties:
        booking:
          $ref: '#/components/schemas/Booking'
        replay:
          type: boolean
    ActionConfirmationRequired:
      type: object
      required:
      - error
      - confirmationToken
      - expiresAt
      properties:
        error:
          type: string
          const: confirmation_required
        confirmationToken:
          type: string
        expiresAt:
          type: string
          format: date-time
      additionalProperties: false
    BookingWrite:
      type: object
      additionalProperties: false
      required:
      - maintenanceEventId
      - preferredPostcode
      properties:
        maintenanceEventId:
          type: string
          format: uuid
        preferredPostcode:
          type: string
          minLength: 1
          maxLength: 80
        preferredDate:
          type:
          - string
          - 'null'
          format: date
        preferredGarage:
          type:
          - string
          - 'null'
          maxLength: 160
        garageEmail:
          type:
          - string
          - 'null'
          format: email
        garagePhone:
          type:
          - string
          - 'null'
          maxLength: 80
        garageWebsite:
          type:
          - string
          - 'null'
          format: uri
        notes:
          type:
          - string
          - 'null'
          maxLength: 1200
    BookingList:
      type: object
      additionalProperties: false
      required:
      - bookings
      properties:
        bookings:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/Booking'
    OutboundResult:
      type: object
      additionalProperties: false
      required:
      - ok
      - replay
      properties:
        ok:
          type: boolean
          const: true
        replay:
          type: boolean
    BookingStatusEnvelope:
      type: object
      additionalProperties: false
      required:
      - booking
      properties:
        booking:
          type: object
          additionalProperties: false
          required:
          - id
          - status
          - updatedAt
          properties:
            id:
              type: string
              format: uuid
            status:
              type: string
            updatedAt:
              type: string
              format: date-time
    BookingStatusWrite:
      type: object
      additionalProperties: false
      required:
      - status
      - expectedUpdatedAt
      properties:
        status:
          type: string
          enum:
          - customer_contacted
          - booked
          - completed
          - cancelled
        expectedUpdatedAt:
          type: string
          format: date-time
    OutboundPreview:
      type: object
      additionalProperties: false
      required:
      - action
      - recipient
      - subject
      - text
      - digest
      - confirmationToken
      - expiresAt
      properties:
        action:
          type: string
          enum:
          - contact.verification.send
          - booking.garage_email.send
        contactId:
          type: string
          format: uuid
        bookingId:
          type: string
          format: uuid
        recipient:
          type: string
          format: email
        subject:
          type: string
          maxLength: 240
        text:
          type: string
          maxLength: 10000
        digest:
          type: string
          pattern: ^[a-f0-9]{64}$
        confirmationToken:
          type: string
        expiresAt:
          type: string
          format: date-time
    Booking:
      type: object
      additionalProperties: false
      required:
      - id
      - maintenanceEventId
      - vehicleId
      - productCategory
      - taskType
      - taskTitle
      - preferredPostcode
      - preferredDate
      - preferredGarage
      - garageEmail
      - garagePhone
      - garageWebsite
      - notes
      - status
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
          format: uuid
        maintenanceEventId:
          type:
          - string
          - 'null'
          format: uuid
        vehicleId:
          type: string
          format: uuid
        productCategory:
          type: string
          maxLength: 32
        taskType:
          type: string
          maxLength: 80
        taskTitle:
          type: string
          maxLength: 160
        preferredPostcode:
          type: string
          maxLength: 80
        preferredDate:
          type:
          - string
          - 'null'
          format: date
        preferredGarage:
          type:
          - string
          - 'null'
          maxLength: 160
        garageEmail:
          type:
          - string
          - 'null'
          format: email
        garagePhone:
          type:
          - string
          - 'null'
          maxLength: 80
        garageWebsite:
          type:
          - string
          - 'null'
          maxLength: 300
        notes:
          type:
          - string
          - 'null'
          maxLength: 1200
        status:
          type: string
          maxLength: 32
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 8
        maxLength: 120
        pattern: ^[A-Za-z0-9._:-]+$
    BookingId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    ActionConfirmation:
      name: X-Fleetkeep-Confirmation
      in: header
      required: false
      schema:
        type: string
      description: Five-minute confirmation token from the immediately preceding unconfirmed request. It is bound to the user, bearer token, exact action, event and current event version.
  responses:
    NotFound:
      description: The requested resource does not exist on the authorised user's account, is the wrong event type, or is immutable history for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ConfirmationConflict:
      description: Confirmation is required, invalid, expired or invalidated by an event update.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/ActionConfirmationRequired'
            - $ref: '#/components/schemas/Error'
    ProviderFailure:
      description: An authorised external provider could not return or accept the requested operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request body or query was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.1 authorisation-code flow with PKCE (S256). End-user delegates per-vehicle access to a partner client. Access tokens expire after 1 hour; refresh tokens (granted with the offline_access scope) live for 30 days.
      flows:
        authorizationCode:
          authorizationUrl: https://fleetkeep.co.uk/auth/oauth2/authorize
          tokenUrl: https://fleetkeep.co.uk/auth/oauth2/token
          refreshUrl: https://fleetkeep.co.uk/auth/oauth2/token
          scopes:
            vehicles:read: Read the authorised user's vehicles and compliance dates.
            vehicles:write: Add, update, delete and bulk-add vehicles on the authorised user's behalf.
            maintenance:read: Read the authorised user's maintenance tasks and completed history.
            maintenance:write: Create, update, complete and cancel the authorised user's maintenance tasks.
            operations:read: Read the authorised user's tracking snapshots, Wex route data and operational defect records.
            operations:write: Report and complete defects on the authorised user's behalf.
            tolls:read: Read the authorised user's toll and clean-air account records, charges and statement previews.
            tolls:write: Create toll and clean-air records and apply confirmed statement imports on the authorised user's behalf.
            documents:read: List and download the authorised user's private vehicle documents.
            documents:write: Create private vehicle document records and uploads on the authorised user's behalf.
            reminders:read: Read reminder settings and contacts.
            reminders:write: Manage reminder settings and contacts, and explicitly confirm verification sends.
            profile:read: Read the authorised user's Fleetkeep account profile.
            guidance:read: Read the authorised user's approved driver guidance and private guidance document.
            exports:read: Download the authorised user's private account and fleet spreadsheet exports.
            offline_access: Issue a refresh token so the partner can refresh access without re-prompting the user.
x-refined-from:
- openapi.json
- fleetkeep-co-uk-openapi.json
x-provenance:
  method: harvested
  publisher: Fleetkeep
  source: https://fleetkeep.co.uk/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)