KeySavvy Reporting API

openapi: 3.2.0
info:
  title: KeySavvy Partner Reporting 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: Reporting
  description: Operations designed to be used for reporting.
paths:
  /reporting/search:
    post:
      tags:
      - Reporting
      summary: Find deals (reporting)
      description: Returns full deal details for matching deals. Designed for reporting purposes. In general, should not be used for end-user-facing features.
      operationId: dealReportingSearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DealReportSearchRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/DealReportSearchResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    ErrorResponseBody:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    AddressResponse:
      type: object
      properties:
        line1:
          type: string
        line2:
          type: string
        city:
          type: string
        state:
          type: string
          pattern: ^[A-Z]{2}$
          description: A US state or territory code.
        zip:
          type: string
          description: Five digits for a US address.
        zip4:
          type: string
          description: 'Omitted when we do not have one.

            '
        country:
          type: string
          pattern: ^[A-Z]{2}$
          description: ISO 3166-1 alpha-2.
      required:
      - line1
      - city
      - state
      - zip
      - country
    DealDetailsResponseBody:
      type: object
      properties:
        referenceId:
          type: string
          pattern: ^[a-zA-Z0-9_-]+$
          description: A stable, unique, case-sensitive partner-supplied ID that identifies this deal.
        marketplaceReferenceId:
          type:
          - string
          - 'null'
          description: The marketplace reference ID associated with this deal.
        displayId:
          type:
          - string
          - 'null'
          description: A user-visible ID for this deal. It can contain any characters, including whitespace.
        displayTitle:
          type:
          - string
          - 'null'
          description: A user-visible title for this deal. This will be displayed prominently at the top of the deal details page when present.
        status:
          $ref: '#/components/schemas/DealStatusEnum'
        statusDescription:
          type: array
          description: 'A human-readable overview of the current status of the deal. This field is intended to provide

            more detailed information to admin / operations.


            Avoid parsing / pre-processing the values returned here as they may be changed without notice.

            Values will not contain any formatting / new-line characters.

            '
          items:
            type: string
        sellers:
          description: List of users with a seller role on this deal.
          type: array
          items:
            $ref: '#/components/schemas/UserWithDealStatus'
        buyers:
          description: 'Current buyers; organization deals list the business representative. Paying or signing as an eligible member makes them representative; other members retain access.

            '
          type: array
          items:
            $ref: '#/components/schemas/UserWithDealStatus'
        dealUrl:
          type: string
          format: uri
          description: An absolute URL to the deal details page associated with this deal. Users should be sent here for all their deal-related needs.
        vehicleReferenceId:
          type: string
          pattern: ^[a-zA-Z0-9_-]+$
          description: A stable, unique, case-sensitive partner-supplied ID for this vehicle
        vehicleDisplayId:
          type:
          - string
          - 'null'
          description: A user-visible ID for this vehicle. It can contain any characters, including whitespace.
        lienholderName:
          type:
          - string
          - 'null'
          description: The lienholder of this vehicle. Can be null if there is no loan, or a seller has not yet provided this information.
        lienholderAccountNumber:
          type:
          - string
          - 'null'
          description: Account number associated with the lienholder
        buyerLenderName:
          type:
          - string
          - 'null'
          description: The name of the buyers lender. Can be null if the buyer does not intend to finance or has not yet provided this information.
        entityBuyer:
          oneOf:
          - $ref: '#/components/schemas/EntityOwnerResponse'
          - type: 'null'
          description: The business purchasing the vehicle on this deal. Null when no business buyer is set on the deal.
        buyerOrganizationReferenceId:
          type:
          - string
          - 'null'
          description: Buyer organization ID; null if none. Membership changes do not update it.
        vin:
          type: string
          description: Vehicle Identification Number
        year:
          type:
          - integer
          - 'null'
          description: Year of the vehicle
        make:
          type:
          - string
          - 'null'
          description: Make of the vehicle
        model:
          type:
          - string
          - 'null'
          description: Model of the vehicle
        color:
          type:
          - string
          - 'null'
          description: Color of the vehicle. See VehicleColorEnum for examples. Additional colors may be added without versioning the API.
        priceCents:
          type:
          - integer
          - 'null'
          description: Current price of the vehicle in cents. Sellers can update their price at any time, but doing so will require everyone to accept the new price. May not be present if seller has not provided a price yet. This is the same as buyerPriceCents and sellerPriceCents.
        buyerPriceCents:
          type:
          - integer
          - 'null'
          description: The base price of the vehicle displayed to the buyer, excluding fees. Equal to sellerPriceCents.
        sellerPriceCents:
          type:
          - integer
          - 'null'
          description: The price the seller agreed to receive, in cents. Currently always equal to priceCents.
        transactionFees:
          $ref: '#/components/schemas/TransactionFees'
        createdAt:
          type: string
          format: date-time
          description: ISO timestamp indicating when this deal was created.
        updatedAt:
          type: string
          format: date-time
          description: ISO timestamp indicating when this deal was last updated.
        paymentVerifiedAt:
          type: string
          format: date-time
          description: ISO timestamp indicating when payment was verified.
        transferConfirmedAt:
          type: string
          format: date-time
          description: ISO timestamp indicating when the vehicle was picked up.
        transferConfirmedMileage:
          type:
          - integer
          - 'null'
          description: The odometer reading (in miles) at the time the vehicle was picked up.
        estimatedTransferDate:
          type:
          - string
          - 'null'
          format: date
          description: The estimated date on which the buyer and seller plan to transfer possession of the vehicle, in YYYY-MM-DD format.
        vehiclePickedUpAt:
          type:
          - string
          - 'null'
          format: date-time
          description: ISO timestamp indicating when the vehicle was picked up for post-pickup inspection.
        postPickupInspectionRequired:
          type:
          - boolean
          - 'null'
          description: When true, the deal requires post-pickup inspection approval before transfer can be completed.
        postPickupInspectionApprovedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: ISO timestamp indicating when the post-pickup inspection was approved.
        visualInspectionCompletedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: ISO timestamp indicating when the vehicle's visual inspection was completed.
        deliveryConfirmationReceivedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: ISO timestamp indicating when we received confirmation from our shipping partner that the vehicle was delivered. This records receipt of the confirmation, not an independently verified delivery time.
        titleSentAt:
          type: string
          format: date-time
          description: ISO timestamp indicating when the title was sent to the buyer.
        loan:
          type:
          - boolean
          - 'null'
          description: Indicates if the vehicle has a loan on it.
        lease:
          type:
          - boolean
          - 'null'
          description: Indicates if the vehicle has a lease.
        registrationState:
          type:
          - string
          - 'null'
          description: The current state that the vehicle is registered in. This should be the abbreviated state name (e.g. CA, TX, NY).
        vehicleLocationZipCode:
          type:
          - string
          - 'null'
          pattern: ^[0-9]{5}$
          description: The 5-digit ZIP code where the vehicle is located.
        billOfLadingUrl:
          type:
          - string
          - 'null'
          format: uri
          description: URL to the bill of lading document if one has been provided
        billOfLadingStatus:
          oneOf:
          - $ref: '#/components/schemas/BillOfLadingStatus'
          - type: 'null'
          description: Current status of the bill of lading for this deal
        canceledAt:
          type:
          - string
          - 'null'
          format: date-time
          description: ISO timestamp when the deal was canceled. When set, indicates this deal has been canceled and will not complete.
      required:
      - referenceId
      - marketplaceReferenceId
      - displayId
      - displayTitle
      - status
      - statusDescription
      - sellers
      - buyers
      - entityBuyer
      - buyerOrganizationReferenceId
      - dealUrl
      - vehicleReferenceId
      - vehicleDisplayId
      - vin
      - year
      - make
      - model
      - color
      - priceCents
      - transactionFees
      - estimatedTransferDate
      - postPickupInspectionRequired
      - vehiclePickedUpAt
      - postPickupInspectionApprovedAt
      - visualInspectionCompletedAt
      - deliveryConfirmationReceivedAt
      - createdAt
      - updatedAt
    UserWithDealStatus:
      type: object
      properties:
        referenceId:
          type: string
          pattern: ^[a-zA-Z0-9_-]+$
          description: Reference ID for a specific user. This is the same as the referenceId used in /user
        actionRequired:
          type: boolean
          description: Indicates if this user has actions they must take in order to progress the deal. These deals should be given visual priority.
    EntityOwnerResponse:
      type: object
      properties:
        name:
          type: string
          description: Name of the business or dealership entity that owns or is purchasing the vehicle.
        address:
          $ref: '#/components/schemas/AddressResponse'
          deprecated: true
          description: Deprecated. Alias of physicalAddress.
        physicalAddress:
          oneOf:
          - $ref: '#/components/schemas/AddressResponse'
          - type: 'null'
          description: The entity's street address. Null when none is set.
        mailingAddress:
          oneOf:
          - $ref: '#/components/schemas/AddressResponse'
          - type: 'null'
          description: Where the entity receives mail. Null when none is set.
        ownerType:
          type: string
          enum:
          - business
          - dealer
          description: Type of entity ownership. Supports 'business' for general business entities and 'dealer' for automotive dealers.
        dealerLicenseState:
          type:
          - string
          - 'null'
          pattern: ^[A-Z]{2}$
          description: The 2-letter state or territory code where the dealer is licensed (e.g. CA, TX, NY). Null when ownerType is not 'dealer', or when no license state is on file.
      required:
      - ownerType
      - physicalAddress
      - mailingAddress
      - dealerLicenseState
    SortOrderEnum:
      type: string
      enum:
      - ASC
      - DESC
    BillOfLadingStatus:
      type: string
      enum:
      - missing
      - uploaded
      description: "Status of the bill of lading for a deal:\n\n * `missing` - No bill of lading has been provided or the bill of lading provided was rejected\n\n * `uploaded` - A bill of lading has been provided (either as a link or uploaded document)\n"
    SearchCriteriaDateTime:
      type: object
      properties:
        gte:
          type: string
          format: date-time
        lte:
          type: string
          format: date-time
    DealStatusEnum:
      type: string
      enum:
      - IN_PROGRESS
      - COMPLETED
      - CANCELED
      description: "Indicates the overall status of this deal:\n\n * `IN_PROGRESS` - The default state of a deal.\n\n * `COMPLETED` - This deal was successful and the vehicle has been transferred. Users should\nstill be provided a way of reaching the `dealUrl` so they can access document records. This is a terminal state, at this point, `actionRequired` will not be `true` again, and the status will not change back to `IN_PROGRESS`.\n\n * `CANCELED` - This deal is incomplete, and is no longer completable. This state can occur\nfor a number of reasons: abandonment, vehicle sold, vehicle removed, user request. This is a terminal state, at this point, `actionRequired` will not be `true` again, and the status will not change back to `IN_PROGRESS`.\n"
    TransactionFees:
      type: object
      properties:
        buyerFeeCents:
          type: integer
          minimum: 0
          description: The portion of the transaction fee the buyer paid, in cents. May be 0.
        sellerFeeCents:
          type: integer
          minimum: 0
          description: The portion of the transaction fee the seller paid, in cents. May be 0.
        totalFeeCents:
          type: integer
          minimum: 0
          description: The total fees charged to both parties. Always the sum of buyerFeeCents and sellerFeeCents.
    DealReportSearchRequestBody:
      type: object
      properties:
        cursor:
          type: string
          description: Return the page of results after this cursor. If not provided, the first page will be returned.
        limit:
          type: integer
          description: The number of results to return per page. Defaults to 25. Max is 25.
          minimum: 1
          maximum: 25
        sortBy:
          type: string
          description: The field to sort by. If not provided, defaults to createdAt.
        order:
          description: The order to sort by. Defaults to ASC.
          $ref: '#/components/schemas/SortOrderEnum'
        status:
          $ref: '#/components/schemas/DealStatusEnum'
        createdAt:
          $ref: '#/components/schemas/SearchCriteriaDateTime'
        paymentVerifiedAt:
          $ref: '#/components/schemas/SearchCriteriaDateTime'
        transferConfirmedAt:
          $ref: '#/components/schemas/SearchCriteriaDateTime'
        titleSentAt:
          $ref: '#/components/schemas/SearchCriteriaDateTime'
    DealReportSearchResponseBody:
      type: object
      properties:
        cursor:
          type: string
          description: When more results are available, use this cursor to fetch the next page.
        hasMore:
          type: boolean
          description: When true, there are more results available. Use the cursor to fetch the next page.
        deals:
          type: array
          items:
            $ref: '#/components/schemas/DealDetailsResponseBody'
      required:
      - deals
      - hasMore
  responses:
    DealReportSearchResponse:
      description: Deal search results for reporting
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DealReportSearchResponseBody'
    ErrorResponse:
      description: The request failed. `error` and `message` describe why.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    UnauthorizedResponse:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: keysavvy-api