KeySavvy Reporting API
Operations designed to be used for reporting.
Operations designed to be used for reporting.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/keysavvy:keysavvy-reporting-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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