KeySavvy KeySavvy Partner API

openapi: 3.2.0
info:
  title: KeySavvy Partner API
  version: 1.0.0
  description: API for KeySavvy Partner integration
  contact:
    name: KeySavvy API Support Team
    email: api-support@keysavvy.com
servers:
- url: https://api.keysavvy.com/v1
  description: KeySavvy Production API
- url: https://api.keysavvy.dev/v1
  description: KeySavvy Non-Production API
security:
- apiKey: []
tags:
- name: KeySavvy Partner API
paths: {}
webhooks:
  user.identity.approved:
    post:
      description: A users identity verification submission has been approved.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserIdentityApprovedWebhookEvent'
      responses:
        2XX:
          description: Return a 2XX status to indicate that the data was received successfully.
      tags:
      - KeySavvy Partner API
      summary: Create user identity approved
      x-summary-source: derived
  deal.transfer.approved:
    post:
      description: A deal's transfer has been approved.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DealTransferApprovedWebhookEvent'
      responses:
        2XX:
          description: Return a 2XX status to indicate that the data was received successfully.
      tags:
      - KeySavvy Partner API
      summary: Create deal transfer approved
      x-summary-source: derived
  deal.transfer.unapproved:
    post:
      description: A deal's transfer has been unapproved.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DealTransferUnapprovedWebhookEvent'
      responses:
        2XX:
          description: Return a 2XX status to indicate that the data was received successfully.
      tags:
      - KeySavvy Partner API
      summary: Create deal transfer unapproved
      x-summary-source: derived
  deal.transfer.confirmed:
    post:
      description: Vehicle transfer has been confirmed. For in-person pickup, transfer is confirmed when the buyer confirms transfer. For shipped vehicles, transfer is confirmed after we receive and verify the Bill of Lading.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DealTransferConfirmedWebhookEvent'
      responses:
        '200':
          description: Return a 2XX status to indicate that the data was received successfully.
      tags:
      - KeySavvy Partner API
      summary: Create deal transfer confirmed
      x-summary-source: derived
  deal.delivery-confirmation.received:
    post:
      description: Our shipping partner has sent confirmation that the vehicle was delivered. This records receipt of the confirmation email, not an independently verified delivery.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DealDeliveryConfirmationReceivedWebhookEvent'
      responses:
        2XX:
          description: Return a 2XX status to indicate that the data was received successfully.
      tags:
      - KeySavvy Partner API
      summary: Create deal delivery confirmation received
      x-summary-source: derived
  deal.payment.unlocked:
    post:
      description: A deal has been approved to proceed to payment. The buyer can now submit payment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DealPaymentUnlockedWebhookEvent'
      responses:
        2XX:
          description: Return a 2XX status to indicate that the data was received successfully.
      tags:
      - KeySavvy Partner API
      summary: Create deal payment unlocked
      x-summary-source: derived
  deal.payment.locked:
    post:
      description: A deal that was previously unlocked for payment has been locked again, for example because the price changed or the deal was canceled. The buyer cannot submit payment until it is unlocked again.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DealPaymentLockedWebhookEvent'
      responses:
        2XX:
          description: Return a 2XX status to indicate that the data was received successfully.
      tags:
      - KeySavvy Partner API
      summary: Create deal payment locked
      x-summary-source: derived
  deal.payment.verified:
    post:
      description: The buyer's payment for a deal has been verified as paid in full.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DealPaymentVerifiedWebhookEvent'
      responses:
        2XX:
          description: Return a 2XX status to indicate that the data was received successfully.
      tags:
      - KeySavvy Partner API
      summary: Create deal payment verified
      x-summary-source: derived
  deal.payment.unverified:
    post:
      description: A deal's payment verification has been revoked, for example because a payment was reversed or the price increased.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DealPaymentUnverifiedWebhookEvent'
      responses:
        2XX:
          description: Return a 2XX status to indicate that the data was received successfully.
      tags:
      - KeySavvy Partner API
      summary: Create deal payment unverified
      x-summary-source: derived
  vehicle.visual-inspection.started:
    post:
      description: A vehicle's visual inspection has been started. The seller has opened the inspection session but has not yet captured any vehicle photos.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VehicleVisualInspectionStartedWebhookEvent'
      responses:
        2XX:
          description: Return a 2XX status to indicate that the data was received successfully.
      tags:
      - KeySavvy Partner API
      summary: Create vehicle visual inspection started
      x-summary-source: derived
  vehicle.visual-inspection.completed:
    post:
      description: A vehicle's visual inspection has been completed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VehicleVisualInspectionCompletedWebhookEvent'
      responses:
        2XX:
          description: Return a 2XX status to indicate that the data was received successfully.
      tags:
      - KeySavvy Partner API
      summary: Create vehicle visual inspection completed
      x-summary-source: derived
components:
  schemas:
    VehicleVisualInspectionCompletedWebhookEvent:
      type: object
      required:
      - type
      - occurredAt
      - data
      properties:
        type:
          type: string
          description: The type of event that occurred.
          const: vehicle.visual-inspection.completed
        occurredAt:
          type: string
          format: date-time
          description: ISO timestamp of when the event occurred.
        data:
          type: object
          description: The data associated with the event.
          required:
          - inspectionId
          - vehicleReferenceId
          properties:
            inspectionId:
              type: string
              description: KeySavvy's identifier for this inspection. Stable across all events for the same inspection.
            vehicleReferenceId:
              type: string
              description: The reference ID of the vehicle associated with this event.
            dealReferenceId:
              type: string
              description: The reference ID of the deal associated with this event, when the inspection was tied to a deal.
            conditionReportUrl:
              type: string
              description: A URL linking to the vehicle's condition report PDF, when available.
            conditionReportPageUrl:
              type: string
              description: A URL linking to the vehicle's condition report landing page (HTML), when available.
    DealPaymentUnverifiedWebhookEvent:
      type: object
      required:
      - type
      - occurredAt
      - data
      properties:
        type:
          type: string
          description: The type of event that occurred.
          const: deal.payment.unverified
        occurredAt:
          type: string
          format: date-time
          description: ISO timestamp of when the event occurred.
        data:
          type: object
          description: The data associated with the event.
          required:
          - vehicleReferenceId
          - dealReferenceId
          properties:
            vehicleReferenceId:
              type: string
              description: The reference ID of the vehicle associated with this event.
            dealReferenceId:
              type: string
              description: The reference ID of the deal associated with this event.
    VehicleVisualInspectionStartedWebhookEvent:
      type: object
      required:
      - type
      - occurredAt
      - data
      properties:
        type:
          type: string
          description: The type of event that occurred.
          const: vehicle.visual-inspection.started
        occurredAt:
          type: string
          format: date-time
          description: ISO timestamp of when the event occurred.
        data:
          type: object
          description: The data associated with the event.
          required:
          - inspectionId
          - vehicleReferenceId
          properties:
            inspectionId:
              type: string
              description: KeySavvy's identifier for this inspection. Stable across all events for the same inspection.
            vehicleReferenceId:
              type: string
              description: The reference ID of the vehicle associated with this event.
            dealReferenceId:
              type: string
              description: The reference ID of the deal associated with this event, when the inspection was tied to a deal.
    DealDeliveryConfirmationReceivedWebhookEvent:
      type: object
      required:
      - type
      - occurredAt
      - data
      properties:
        type:
          type: string
          description: The type of event that occurred.
          const: deal.delivery-confirmation.received
        occurredAt:
          type: string
          format: date-time
          description: ISO timestamp of when the event occurred.
        data:
          type: object
          description: The data associated with the event.
          required:
          - vehicleReferenceId
          - dealReferenceId
          properties:
            vehicleReferenceId:
              type: string
              description: The reference ID of the vehicle associated with this event.
            dealReferenceId:
              type: string
              description: The reference ID of the deal associated with this event.
    DealPaymentVerifiedWebhookEvent:
      type: object
      required:
      - type
      - occurredAt
      - data
      properties:
        type:
          type: string
          description: The type of event that occurred.
          const: deal.payment.verified
        occurredAt:
          type: string
          format: date-time
          description: ISO timestamp of when the event occurred.
        data:
          type: object
          description: The data associated with the event.
          required:
          - vehicleReferenceId
          - dealReferenceId
          properties:
            vehicleReferenceId:
              type: string
              description: The reference ID of the vehicle associated with this event.
            dealReferenceId:
              type: string
              description: The reference ID of the deal associated with this event.
    DealPaymentLockedWebhookEvent:
      type: object
      required:
      - type
      - occurredAt
      - data
      properties:
        type:
          type: string
          description: The type of event that occurred.
          const: deal.payment.locked
        occurredAt:
          type: string
          format: date-time
          description: ISO timestamp of when the event occurred.
        data:
          type: object
          description: The data associated with the event.
          required:
          - vehicleReferenceId
          - dealReferenceId
          properties:
            vehicleReferenceId:
              type: string
              description: The reference ID of the vehicle associated with this event.
            dealReferenceId:
              type: string
              description: The reference ID of the deal associated with this event.
    UserIdentityApprovedWebhookEvent:
      type: object
      required:
      - type
      - occurredAt
      - data
      properties:
        type:
          type: string
          description: The type of event that occurred.
          const: user.identity.approved
        occurredAt:
          type: string
          format: date-time
          description: ISO timestamp of when the event occurred.
        data:
          type: object
          description: The data associated with the event.
          required:
          - userReferenceId
          properties:
            userReferenceId:
              type: string
              description: The reference ID of the user associated with this event.
    DealTransferUnapprovedWebhookEvent:
      type: object
      required:
      - type
      - occurredAt
      - data
      properties:
        type:
          type: string
          description: The type of event that occurred.
          const: deal.transfer.unapproved
        occurredAt:
          type: string
          format: date-time
          description: ISO timestamp of when the event occurred.
        data:
          type: object
          description: The data associated with the event.
          required:
          - vehicleReferenceId
          - dealReferenceId
          properties:
            vehicleReferenceId:
              type: string
              description: The reference ID of the vehicle associated with this event.
            dealReferenceId:
              type: string
              description: The reference ID of the deal associated with this event.
    DealTransferApprovedWebhookEvent:
      type: object
      required:
      - type
      - occurredAt
      - data
      properties:
        type:
          type: string
          description: The type of event that occurred.
          const: deal.transfer.approved
        occurredAt:
          type: string
          format: date-time
          description: ISO timestamp of when the event occurred.
        data:
          type: object
          description: The data associated with the event.
          required:
          - vehicleReferenceId
          - dealReferenceId
          properties:
            vehicleReferenceId:
              type: string
              description: The reference ID of the vehicle associated with this event.
            dealReferenceId:
              type: string
              description: The reference ID of the deal associated with this event.
    DealTransferConfirmedWebhookEvent:
      type: object
      required:
      - type
      - occurredAt
      - data
      properties:
        type:
          type: string
          description: The type of event that occurred.
          const: deal.transfer.confirmed
        occurredAt:
          type: string
          format: date-time
          description: ISO timestamp of when the event occurred.
        data:
          type: object
          description: The data associated with the event.
          required:
          - vehicleReferenceId
          - dealReferenceId
          - deliveryType
          properties:
            vehicleReferenceId:
              type: string
              description: The reference ID of the vehicle associated with this event.
            dealReferenceId:
              type: string
              description: The reference ID of the deal associated with this event.
            deliveryType:
              type: string
              enum:
              - SHIP
              - LOCAL_PICKUP
              description: How the buyer took possession of the vehicle.
            mileage:
              type:
              - integer
              - 'null'
              description: The mileage of the vehicle at the time of transfer, if available.
            billOfLadingUrl:
              type:
              - string
              - 'null'
              description: URL to the bill of lading document if one has been provided
    DealPaymentUnlockedWebhookEvent:
      type: object
      required:
      - type
      - occurredAt
      - data
      properties:
        type:
          type: string
          description: The type of event that occurred.
          const: deal.payment.unlocked
        occurredAt:
          type: string
          format: date-time
          description: ISO timestamp of when the event occurred.
        data:
          type: object
          description: The data associated with the event.
          required:
          - vehicleReferenceId
          - dealReferenceId
          properties:
            vehicleReferenceId:
              type: string
              description: The reference ID of the vehicle associated with this event.
            dealReferenceId:
              type: string
              description: The reference ID of the deal associated with this event.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: keysavvy-api