Fleetkeep Reminders API

openapi: 3.2.0
info:
  title: Fleetkeep Co Uk Reminders 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 Reminders 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: Reminders
  description: Manage consented reminder settings and contacts. External verification is previewed and confirmed separately.
paths:
  /api/v1/settings/reminders:
    get:
      tags:
      - Reminders
      operationId: getReminderSettings
      security:
      - oauth2:
        - reminders:read
      responses:
        '200':
          description: Settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReminderSettings'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      summary: Get reminder settings
      x-summary-source: derived
    put:
      tags:
      - Reminders
      operationId: updateReminderSettings
      security:
      - oauth2:
        - reminders:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReminderSettingsWrite'
      responses:
        '200':
          description: Settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReminderSettings'
        '400':
          $ref: '#/components/responses/BadRequest'
      summary: Update reminder settings
      x-summary-source: derived
    servers:
    - url: https://fleetkeep.co.uk
      description: Production
  /api/v1/vehicles/{id}/reminders:
    get:
      tags:
      - Reminders
      operationId: getVehicleReminderRecipients
      security:
      - oauth2:
        - reminders:read
      parameters:
      - $ref: '#/components/parameters/VehicleId'
      responses:
        '200':
          description: Vehicle reminder recipients
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VehicleReminderSettings'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Get vehicle reminder recipients
      x-summary-source: derived
    put:
      tags:
      - Reminders
      operationId: replaceVehicleReminderRecipients
      security:
      - oauth2:
        - reminders:write
      parameters:
      - $ref: '#/components/parameters/VehicleId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/VehicleReminderRecipientsWrite'
              - $ref: '#/components/schemas/ReminderIntervalsWrite'
      responses:
        '200':
          description: Updated recipients
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/VehicleReminderRecipients'
                - $ref: '#/components/schemas/ReminderIntervals'
        '400':
          $ref: '#/components/responses/BadRequest'
      summary: Replace vehicle reminder recipients
      x-summary-source: derived
    post:
      tags:
      - Reminders
      operationId: createMobileVehicleReminderRecipient
      description: Compatibility operation available only to the verified Fleetkeep mobile client. It adds the contact, assigns it to this vehicle and attempts its consent email.
      security:
      - oauth2:
        - reminders:write
      parameters:
      - $ref: '#/components/parameters/VehicleId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactWrite'
      responses:
        '201':
          description: Recipient assignment and confirmation outcome
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VehicleReminderMobileResult'
        '409':
          $ref: '#/components/responses/ConfirmationConflict'
      summary: Create mobile vehicle reminder recipient
      x-summary-source: derived
    servers:
    - url: https://fleetkeep.co.uk
      description: Production
  /api/v1/contacts:
    get:
      tags:
      - Reminders
      operationId: listContacts
      security:
      - oauth2:
        - reminders:read
      responses:
        '200':
          description: Contacts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
      summary: List contacts
      x-summary-source: derived
    post:
      tags:
      - Reminders
      operationId: createContact
      security:
      - oauth2:
        - reminders:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactWrite'
      responses:
        '200':
          description: Existing contact replayed without sending email
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactEnvelope'
        '201':
          description: Created without sending email
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
      summary: Create contact
      x-summary-source: derived
    servers:
    - url: https://fleetkeep.co.uk
      description: Production
  /api/v1/contacts/{id}:
    delete:
      tags:
      - Reminders
      operationId: deleteContact
      security:
      - oauth2:
        - reminders:write
      parameters:
      - $ref: '#/components/parameters/ContactId'
      - $ref: '#/components/parameters/ActionConfirmation'
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/ConfirmationConflict'
      summary: Delete contact
      x-summary-source: derived
    servers:
    - url: https://fleetkeep.co.uk
      description: Production
  /api/v1/contacts/{id}/verification/preview:
    post:
      tags:
      - Reminders
      operationId: previewContactVerification
      security:
      - oauth2:
        - reminders:write
      parameters:
      - $ref: '#/components/parameters/ContactId'
      responses:
        '200':
          description: Five-minute confirmation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundPreview'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Preview contact verification
      x-summary-source: derived
    servers:
    - url: https://fleetkeep.co.uk
      description: Production
  /api/v1/contacts/{id}/verification/send:
    post:
      tags:
      - Reminders
      operationId: sendContactVerification
      security:
      - oauth2:
        - reminders:write
      parameters:
      - $ref: '#/components/parameters/ContactId'
      - $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 contact verification
      x-summary-source: derived
    servers:
    - url: https://fleetkeep.co.uk
      description: Production
components:
  responses:
    Unauthorized:
      description: Missing or invalid Bearer access token.
      content:
        application/json:
          schema:
            $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'
    Forbidden:
      description: Token does not include the required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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'
    BadRequest:
      description: The request body or query was invalid.
      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'
  schemas:
    VehicleReminderRecipients:
      type: object
      additionalProperties: false
      required:
      - primaryEmail
      - contacts
      properties:
        primaryEmail:
          type: string
          format: email
        contacts:
          type: array
          maxItems: 5
          items:
            $ref: '#/components/schemas/VehicleReminderContact'
    VehicleReminderMobileResult:
      type: object
      additionalProperties: false
      required:
      - primaryEmail
      - contacts
      - confirmationSent
      properties:
        primaryEmail:
          type: string
          format: email
        contacts:
          type: array
          maxItems: 5
          items:
            $ref: '#/components/schemas/VehicleReminderContact'
        confirmationSent:
          type: boolean
    VehicleReminderRecipientsWrite:
      type: object
      additionalProperties: false
      required:
      - contactIds
      properties:
        contactIds:
          type: array
          maxItems: 5
          uniqueItems: true
          items:
            type: string
            format: uuid
    ContactList:
      type: object
      additionalProperties: false
      required:
      - contacts
      properties:
        contacts:
          type: array
          maxItems: 5
          items:
            $ref: '#/components/schemas/Contact'
    ReminderIntervalsWrite:
      $ref: '#/components/schemas/ReminderIntervals'
    VehicleReminderSettings:
      type: object
      additionalProperties: false
      required:
      - intervals
      - primaryEmail
      - contacts
      properties:
        intervals:
          $ref: '#/components/schemas/ReminderIntervals/properties/intervals'
        primaryEmail:
          type: string
          format: email
        contacts:
          type: array
          maxItems: 5
          items:
            $ref: '#/components/schemas/VehicleReminderContact'
    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
    VehicleReminderContact:
      type: object
      additionalProperties: false
      required:
      - id
      - email
      - name
      - verifiedAt
      - unsubscribedAt
      - unsubscribeReason
      - selected
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type:
          - string
          - 'null'
          maxLength: 160
        verifiedAt:
          type:
          - string
          - 'null'
          format: date-time
        unsubscribedAt:
          type:
          - string
          - 'null'
          format: date-time
        unsubscribeReason:
          type:
          - string
          - 'null'
          maxLength: 500
        selected:
          type: boolean
    ReminderSettingsWrite:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        enabled:
          type: boolean
        intervals:
          type: array
          minItems: 1
          maxItems: 8
          uniqueItems: true
          items:
            type: integer
            minimum: 1
            maximum: 365
    ReminderIntervals:
      type: object
      additionalProperties: false
      required:
      - intervals
      properties:
        intervals:
          type: array
          minItems: 1
          maxItems: 8
          uniqueItems: true
          items:
            type: integer
            minimum: 1
            maximum: 365
    ContactWrite:
      type: object
      additionalProperties: false
      required:
      - email
      properties:
        email:
          type: string
          format: email
          maxLength: 254
        name:
          type: string
          maxLength: 160
    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
    Contact:
      type: object
      additionalProperties: false
      required:
      - id
      - name
      - email
      - verificationStatus
      - selectedVehicleCount
      - createdAt
      properties:
        id:
          type: string
          format: uuid
        name:
          type:
          - string
          - 'null'
          maxLength: 160
        email:
          type: string
          format: email
          maxLength: 254
        verificationStatus:
          type: string
          enum:
          - pending
          - verified
          - unsubscribed
        selectedVehicleCount:
          type: integer
          minimum: 0
          maximum: 50
        createdAt:
          type: string
          format: date-time
    OutboundResult:
      type: object
      additionalProperties: false
      required:
      - ok
      - replay
      properties:
        ok:
          type: boolean
          const: true
        replay:
          type: boolean
    ReminderSettings:
      type: object
      additionalProperties: false
      required:
      - enabled
      - intervals
      properties:
        enabled:
          type: boolean
        intervals:
          type: array
          minItems: 1
          maxItems: 8
          uniqueItems: true
          items:
            type: integer
            minimum: 1
            maximum: 365
    Error:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error:
          type: string
          example: registration_required
    ContactEnvelope:
      type: object
      additionalProperties: false
      required:
      - contact
      properties:
        contact:
          $ref: '#/components/schemas/Contact'
        replay:
          type: boolean
  parameters:
    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.
    VehicleId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    ContactId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 8
        maxLength: 120
        pattern: ^[A-Za-z0-9._:-]+$
  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)