openapi: 3.1.2 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 tags: - name: User Management description: Operations related to user management. - name: Deal Management description: Operations related to deal management. - name: Authentication description: Operations related to authentication. - name: Marketplace Management description: Operations related to marketplace themes. - name: Reporting description: Operations designed to be used for reporting. servers: - url: https://api.keysavvy.com/v1 description: KeySavvy Production API - url: https://api.keysavvy.dev/v1 description: KeySavvy Non-Production API paths: /marketplace: post: tags: - Marketplace Management summary: Create a new marketplace description: Creates a new marketplace and its associated theme information (excluding logo images). This can be referenced when creating new deals, vehicles, and users. operationId: createMarketplace requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MarketplaceCreateRequestBody" responses: "201": $ref: "#/components/responses/MarketplaceDetailsResponse" "400": $ref: "#/components/responses/ErrorResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "403": $ref: "#/components/responses/ErrorResponse" "409": $ref: "#/components/responses/ErrorResponse" /marketplace/{referenceId}: get: tags: - Marketplace Management summary: Gets current information about a given marketplace. description: Returns marketplace information if the provided referenceId exists operationId: getMarketplace parameters: - name: referenceId in: path description: Reference ID of the marketplace. required: true schema: type: string responses: "200": $ref: "#/components/responses/MarketplaceDetailsResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "404": $ref: "#/components/responses/ErrorResponse" patch: tags: - Marketplace Management summary: Update marketplace information. description: Updates information for the given marketplace if it exists. operationId: updateMarketplace parameters: - name: referenceId in: path description: Reference ID of the marketplace. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MarketplaceUpdateRequestBody" responses: "200": $ref: "#/components/responses/MarketplaceDetailsResponse" "400": $ref: "#/components/responses/ErrorResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "404": $ref: "#/components/responses/ErrorResponse" /marketplace/{referenceId}/logo: post: tags: - Marketplace Management summary: Uploads a new logo for the provided marketplace. description: > Creates or replaces and existing logo for the given marketplace. The maximum file size for a logo is 1 MB. operationId: uploadMarketplaceLogo parameters: - name: referenceId in: path description: Reference ID of the marketplace. required: true schema: type: string requestBody: required: true content: multipart/form-data: schema: $ref: "#/components/schemas/MarketplaceLogoUploadRequestBody" responses: "200": $ref: "#/components/responses/MarketplaceDetailsResponse" "400": $ref: "#/components/responses/ErrorResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "404": $ref: "#/components/responses/ErrorResponse" /user: post: tags: - User Management summary: Create or activate user description: Creates or activates a user after the user has consented to information sharing/agreed to the terms of service. operationId: createUser requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UserCreateRequestBody" responses: "201": $ref: "#/components/responses/CreatedResponse" "400": $ref: "#/components/responses/ErrorResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "409": $ref: "#/components/responses/ErrorResponse" /user/{referenceId}: get: tags: - User Management summary: Get existing user description: Returns KeySavvy account information for a user if they exist. operationId: getUserDetails parameters: - name: referenceId in: path description: Reference ID of the user. required: true schema: type: string responses: "200": $ref: "#/components/responses/UserDetailsResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "404": $ref: "#/components/responses/ErrorResponse" post: tags: - User Management summary: Update user description: > Updates an existing user. Currently, only email address updates are supported by API, but users can update other personal information (name, address, etc.) directly on the white label site. operationId: updateUser parameters: - name: referenceId in: path description: Reference ID of the user to update. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UserUpdateRequestBody" responses: "200": $ref: "#/components/responses/UpdatedResponse" "400": $ref: "#/components/responses/ErrorResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "404": $ref: "#/components/responses/ErrorResponse" /user/{referenceId}/summary: get: tags: - User Management summary: Get user deals summary description: > Returns summary information about a user's deals. Does not return user PII or account info. If the provided reference ID is totally unknown to KeySavvy the response status will be 404, but the response body will still be a valid summary. This endpoint returns information from the perspective of the user being summarized. Some data fields (e.g. lienholderName, buyerLenderName) are party / user specific and will not returned if they are not normally visible to the user. operationId: getUserSummary parameters: - name: referenceId in: path description: Reference ID of the user. required: true schema: type: string responses: "200": $ref: "#/components/responses/UserSummaryResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "404": $ref: "#/components/responses/UserSummaryResponse" /user/{referenceId}/login-link: post: tags: - User Management - Authentication summary: Send login link description: Sends a user an email containing a magic login link that will allow them to log in directly to the white label site. Bypasses partner site authentication. operationId: sendUserMagicLoginLink parameters: - name: referenceId in: path description: Reference ID of the user to send the login link to. required: true schema: type: string responses: "200": $ref: "#/components/responses/CreatedResponse" "400": $ref: "#/components/responses/ErrorResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "404": $ref: "#/components/responses/ErrorResponse" /user/{userReferenceId}/document: post: tags: - Documents - User Management summary: Upload user document description: > Uploads a document associated with the provided user reference ID, such as a dealer license. The maximum file size for a single document is 10 MB. operationId: uploadUserDocument parameters: - name: userReferenceId in: path description: Reference ID of the user this document belongs to. required: true schema: type: string requestBody: required: true content: multipart/form-data: schema: $ref: "#/components/schemas/UserDocumentCreateRequestBody" responses: "201": $ref: "#/components/responses/CreatedResponse" "400": $ref: "#/components/responses/ErrorResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "404": $ref: "#/components/responses/ErrorResponse" /vehicle: post: tags: - Vehicle Management summary: Create new vehicle description: > Creates a new vehicle for a seller. If you already know the buyer & seller of this vehicle (e.g. this is the result of an auction closing) you should use the createDeal operation instead. If the provided vehicleReferenceId already exists, this will return a 409 error response. operationId: createVehicle requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/VehicleCreateRequestBody" responses: "201": $ref: "#/components/responses/VehicleCreatedResponse" "400": $ref: "#/components/responses/ErrorResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "409": $ref: "#/components/responses/ErrorResponse" /vehicle/{referenceId}: get: tags: - Vehicle Management summary: Get existing vehicle description: Returns vehicle information if the provided reference ID exists. operationId: getVehicleDetails parameters: - name: referenceId in: path description: Reference ID of the vehicle. required: true schema: type: string responses: "200": $ref: "#/components/responses/VehicleDetailsResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "404": $ref: "#/components/responses/ErrorResponse" /vehicle/{vehicleReferenceId}/document: post: tags: - Documents - Vehicle Management summary: Upload vehicle document description: > Uploads a document associated with the provided vehicle reference ID, such as a title image, registration photo, etc. The maximum file size for a single document is 10 MB. operationId: uploadVehicleDocument parameters: - name: vehicleReferenceId in: path description: Reference ID of the vehicle this document belongs to. required: true schema: type: string requestBody: required: true content: multipart/form-data: schema: $ref: "#/components/schemas/VehicleDocumentCreateRequestBody" responses: "200": $ref: "#/components/responses/CreatedResponse" "400": $ref: "#/components/responses/ErrorResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "404": $ref: "#/components/responses/ErrorResponse" /deal/{referenceId}/bill-of-lading-link: post: tags: - Deal Documents summary: Submit bill of lading URL description: Upload a bill of lading URL from an online shipping platform (e.g. Super Dispatch). If mileage at pickup is known, you can also provide vehicle mileage. operationId: uploadBillOfLadingLink parameters: - name: referenceId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/BillOfLadingLinkRequestBody" responses: "201": $ref: "#/components/responses/CreatedResponse" "400": $ref: "#/components/responses/ErrorResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "404": $ref: "#/components/responses/ErrorResponse" /deal/{referenceId}/bill-of-lading-upload: post: tags: - Deal Documents summary: Upload bill of lading document description: Upload a bill of lading file (image or PDF). If a file has already been uploaded, the existing one will be archived and will be replaced by the new file. operationId: uploadBillOfLading parameters: - name: referenceId in: path required: true schema: type: string requestBody: required: true content: multipart/form-data: schema: $ref: "#/components/schemas/BillOfLadingUploadRequestBody" responses: "201": $ref: "#/components/responses/CreatedResponse" "400": $ref: "#/components/responses/ErrorResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "404": $ref: "#/components/responses/ErrorResponse" /vehicle/{vehicleReferenceId}/deal: post: tags: - Vehicle Management summary: Create deal for existing vehicle description: > Creates a new deal between the buyerReferenceId identified in the request body and the vehicleReferenceId identified in the path. Optionally, a unique dealReferenceId can be provided to identify this specific deal. If no dealReferenceId is provided, one will be generated. operationId: createVehicleDeal parameters: - name: vehicleReferenceId in: path description: Reference ID of the vehicle to create a deal for. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/VehicleDealCreateRequestBody" responses: "201": $ref: "#/components/responses/VehicleDealCreatedResponse" "400": $ref: "#/components/responses/ErrorResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "404": $ref: "#/components/responses/ErrorResponse" "409": $ref: "#/components/responses/ErrorResponse" /deal: post: tags: - Deal Management summary: Create new deal description: Creates a new deal between a seller and a buyer for a specific vehicle. operationId: createDeal requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DealCreateRequestBody" responses: "201": $ref: "#/components/responses/CreatedResponse" "400": $ref: "#/components/responses/ErrorResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "409": $ref: "#/components/responses/ErrorResponse" /deal/{referenceId}: get: tags: - Deal Management summary: Get existing deal description: Returns deal information if the provided reference ID exists. operationId: getDealDetails parameters: - name: referenceId in: path description: Reference ID of the deal. required: true schema: type: string responses: "200": $ref: "#/components/responses/DealDetailsResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "404": $ref: "#/components/responses/ErrorResponse" /deal/{referenceId}/cancel: post: tags: - Deal Management summary: Cancel a deal description: "Cancels a deal. This is a one-way action - deals cannot be un-canceled. Canceled deals will still be returned by the API with the canceledAt timestamp set. A deal cannot be canceled if: (1) the transfer has been confirmed, or (2) the buyer has paid and has not been refunded." operationId: cancelDeal parameters: - name: referenceId in: path description: Reference ID of the deal to cancel. required: true schema: type: string responses: "200": $ref: "#/components/responses/UpdatedResponse" "400": $ref: "#/components/responses/ErrorResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "404": $ref: "#/components/responses/ErrorResponse" "409": $ref: "#/components/responses/CancelDealConflictResponse" /deal/{dealReferenceId}/vehicle/document: post: tags: - Documents - Vehicle Management summary: Upload vehicle document for deal description: > Uploads a document to the vehicle associated with the provided deal, such as a title image, registration photo, etc. The maximum file size for a single document is 10 MB. operationId: uploadDealVehicleDocument parameters: - name: dealReferenceId in: path description: Reference ID of a deal associated with the vehicle this document belongs to. required: true schema: type: string requestBody: required: true content: multipart/form-data: schema: $ref: "#/components/schemas/VehicleDocumentCreateRequestBody" responses: "200": $ref: "#/components/responses/CreatedResponse" "400": $ref: "#/components/responses/ErrorResponse" "401": $ref: "#/components/responses/UnauthorizedResponse" "404": $ref: "#/components/responses/ErrorResponse" /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" /auth: post: tags: - Authentication summary: Authenticate user description: > Authenticates a user and returns a very short-lived single-use token/url that the user should be redirected to in order to obtain a KeySavvy session token. There are two distinct ways you can choose to handle user auth: #### Direct 1. Redirect the customer (either directly, or client side) to the `directRedirectUrl` value provided by this response. #### Cookie 1. Include a secure, httpOnly, Set-Cookie header with a 15 second TTL in your response to the end-user. The cookie name and value are provided in this response as `cookieName` and `cookieValue`. 2. Redirect the customer (either directly, or client side) to the `cookieRedirectUrl` value provided by this response. operationId: authenticateUser requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AuthRequestBody" responses: "200": description: Authentication successful content: application/json: schema: $ref: "#/components/schemas/AuthResponseBody" "400": description: Authentication unsuccessful, see response code for details content: application/json: schema: $ref: "#/components/schemas/AuthErrorResponseBody" "401": $ref: "#/components/responses/UnauthorizedResponse" "404": $ref: "#/components/responses/ErrorResponse" components: responses: AcceptedResponse: description: Resource accepted successfully content: application/json: schema: $ref: "#/components/schemas/AcceptedResponseBody" CreatedResponse: description: Resource created successfully content: application/json: schema: $ref: "#/components/schemas/CreatedResponseBody" UpdatedResponse: description: Resource updated successfully content: application/json: schema: $ref: "#/components/schemas/UpdatedResponseBody" ErrorResponse: description: Generic error response. The error field should indicate what went wrong. content: application/json: schema: $ref: "#/components/schemas/ErrorResponseBody" UnauthorizedResponse: description: Authentication failed content: application/json: schema: $ref: "#/components/schemas/ErrorResponseBody" UserSummaryResponse: description: Summary information about a user's current / past deals. content: application/json: schema: $ref: "#/components/schemas/UserSummaryResponseBody" UserDetailsResponse: description: User account information content: application/json: schema: $ref: "#/components/schemas/UserDetailsResponseBody" MarketplaceDetailsResponse: description: Marketplace information content: application/json: schema: $ref: "#/components/schemas/MarketplaceDetailsResponseBody" DealDetailsResponse: description: Deal information content: application/json: schema: $ref: "#/components/schemas/DealDetailsResponseBody" VehicleCreatedResponse: description: Created vehicle information content: application/json: schema: $ref: "#/components/schemas/VehicleCreateResponseBody" VehicleDealCreatedResponse: description: Created deal information content: application/json: schema: $ref: "#/components/schemas/VehicleDealCreateResponseBody" VehicleDetailsResponse: description: Vehicle information content: application/json: schema: $ref: "#/components/schemas/VehicleDetailsResponseBody" DealReportSearchResponse: description: Deal search results for reporting content: application/json: schema: $ref: "#/components/schemas/DealReportSearchResponseBody" CancelDealConflictResponse: description: Deal cannot be canceled due to its current state content: application/json: schema: $ref: "#/components/schemas/CancelDealConflictErrorResponseBody" schemas: Address: type: object properties: line1: type: string line2: type: string city: type: string state: type: string zip: type: string zip4: type: string country: type: string description: Only "US" is supported required: - line1 - city - state - zip - country VehicleColorEnum: type: string enum: - BLACK - BLUE - BROWN - GOLD - GRAY - GREEN - ORANGE - PINK - PURPLE - RED - SILVER - WHITE - YELLOW description: The approximate color of the vehicle. EntityOwner: 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/Address" 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: Optional dealer license state. The 2-letter state code where the dealer is licensed (e.g. CA, TX, NY). required: - ownerType DealRoleEnum: type: string enum: - BUYER - SELLER description: > Indicates the role of this user in this specific deal: * `BUYER` - The user is a buyer. Joint purchase is supported, but this user will handle interaction with KeySavvy. * `SELLER` - This user is a seller. DealStatusEnum: type: string enum: - IN_PROGRESS - COMPLETED - CANCELED description: > Indicates the overall status of this deal: * `IN_PROGRESS` - The default state of a deal. * `COMPLETED` - This deal was successful and the vehicle has been transferred. Users should still 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`. * `CANCELED` - This deal is incomplete, and is no longer completable. This state can occur for 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`. 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" SortOrderEnum: type: string enum: - ASC - DESC BusinessTypeEnum: type: string enum: - dealer description: Indicates if the user is a business. Supports 'dealer' for automotive dealers. BillOfLadingStatus: type: string enum: - missing - uploaded description: > Status of the bill of lading for a deal: * `missing` - No bill of lading has been provided or the bill of lading provided was rejected * `uploaded` - A bill of lading has been provided (either as a link or uploaded document) SearchCriteriaDateTime: type: object properties: gte: type: string format: date-time lte: type: string format: date-time 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. MarketplaceDetailsResponseBody: type: object required: - referenceId - commonName - mobileLogoUrl - desktopLogoUrl - emailLogoUrl - color properties: referenceId: type: string commonName: type: string mobileLogoUrl: type: - string - "null" description: URL of the logo to be displayed in the header at mobile breakpoints. If this is missing, your default logo is used. desktopLogoUrl: type: - string - "null" description: URL of the logo to be displayed in the header at mobile breakpoints. If this is missing, the mobileLogoUrl is used. emailLogoUrl: type: - string - "null" description: URL of the logo to be displayed in the header at mobile breakpoints. If this is missing, the desktopLogoUrl is used. color: type: - string - "null" MarketplaceCreateRequestBody: type: object required: - referenceId - name properties: referenceId: type: string pattern: ^[a-zA-Z0-9_-]+$ description: A stable, unique, case-sensitive partner-supplied ID for this marketplace. This is how you will associate vehicles & deals with a marketplace. name: type: string description: The user facing name of this marketplace. This value is displayed in various places throughout the UI & emails. color: type: string pattern: ^#[A-F0-9]{6}$ description: "Optional hex color (e.g. #FF99CC) to be used as the primary accent color. If not provided, your default theme color will be used." mobileLogo: type: string description: Displayed in the header at mobile breakpoints. This image will be aspect scaled to fit 220px x 40px. May be provided as base64 image data, or an absolute URL to the image. E.g. "data:image/png;base64,..." or "https://..." desktopLogo: type: string description: Displayed in the header at mobile breakpoints. This image will be aspect scaled to fit 250px x 100px. May be provided as base64 image data, or an absolute URL to the image. E.g. "data:image/png;base64,..." or "https://..." emailLogo: type: string description: Displayed in the header at mobile breakpoints. This image will be aspect scaled to fit 400px x 200px. May be provided as base64 image data, or an absolute URL to the image. E.g. "data:image/png;base64,..." or "https://..." MarketplaceUpdateRequestBody: type: object properties: name: type: string description: The user facing name of this marketplace. This value is displayed in various places throughout the UI & emails. color: type: string pattern: ^#[A-F0-9]{6}$ description: "Hex color (e.g. #FF99CC) to be used as the primary accent color. If this is null, your default theme color will be used." mobileLogo: type: string description: Displayed in the header at mobile breakpoints. This image will be aspect scaled to fit 220px x 40px. May be provided as base64 image data, or an absolute URL to the image. E.g. "data:image/png;base64,..." or "https://..." desktopLogo: type: string description: Displayed in the header at mobile breakpoints. This image will be aspect scaled to fit 250px x 100px. May be provided as base64 image data, or an absolute URL to the image. E.g. "data:image/png;base64,..." or "https://..." emailLogo: type: string description: Displayed in the header at mobile breakpoints. This image will be aspect scaled to fit 400px x 200px. May be provided as base64 image data, or an absolute URL to the image. E.g. "data:image/png;base64,..." or "https://..." MarketplaceLogoUploadRequestBody: type: object required: - type - file properties: type: type: string description: > The type of logo being uploaded. Types: * `mobile` - Displayed in the header at mobile breakpoints. This will be aspect scaled to fit within 40px x 230px bounds. * `desktop` - Displayed in the header at desktop breakpoints. This will be aspect scaled to fit within 50px x 250px bounds. * `email` - Displayed at the top of emails. This will be aspect scaled to fit within 400px x 200px bounds. enum: - mobile - desktop - email file: type: string format: binary description: The logo file being uploaded. This file must be an image (image/* mime-type). 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 AuthRequestBody: type: object properties: userReferenceId: type: string pattern: ^[a-zA-Z0-9_-]+$ description: The reference ID of the user to authenticate. impersonatorReferenceId: type: string pattern: ^[a-zA-Z0-9_-]+$ description: This field should uniquely identify a partner admin if they are impersonating the customer referenced in userReferenceId. redirectPath: type: string description: An optional post-auth redirection path. Invalid, or non-relative URL paths will be ignored. required: - userReferenceId AuthResponseBody: type: object properties: cookieValue: type: string description: The cookie value that callers should include in their response to the end user. cookieName: type: string description: The cookie name that callers should include in their response to the end user. cookieRedirectUrl: type: string format: uri description: An absolute URL that the end-user should be redirected to after setting the provided `cookieName` and `cookieValue`. directRedirectUrl: type: string format: uri description: An absolute URL that the end-user should be redirected to after this auth is complete. This URL does not require setting any cookies before use. AuthErrorResponseBody: type: object properties: code: type: string enum: - USER_NOT_ACTIVATED description: > Indicates the reason this auth request failed: * `USER_NOT_ACTIVATED` - This reference ID is associated with one or more deals, but needs to be activated with a call to `POST /user` before the user can be authed. error: type: string UserCreateRequestBody: type: object properties: referenceId: type: string pattern: ^[a-zA-Z0-9_-]+$ description: A stable, unique, case-sensitive partner-supplied ID for this user. firstName: type: string lastName: type: string email: type: string format: email physicalAddress: $ref: "#/components/schemas/Address" phoneNumber: type: string description: "The expected format of the phoneNumber field is e.164 (example: +12065556666)" businessRepresentative: $ref: "#/components/schemas/EntityOwner" description: > When the user is a representative of a business or dealership, all vehicles and deals created by this user will automatically include the business information as the buyer or seller information. businessType: deprecated: true description: Deprecated. Use businessRepresentative instead. oneOf: - $ref: "#/components/schemas/BusinessTypeEnum" - type: "null" avatarUrl: type: - string - "null" format: uri description: "Recommended size: 100px x 100px, 1:1 aspect ratio; JPG, PNG, webp, or avif. Must start with https://" required: - referenceId - email UserUpdateRequestBody: type: object properties: email: type: string format: email UserDetailsResponseBody: type: object required: - referenceId - email - activated - phoneNumber - avatarUrl - physicalAddress - mailingAddress - businessType properties: referenceId: type: string activated: type: boolean description: This value is true if a user with this referenceId has been added to KeySavvy using the createUser /user endpoint. email: type: - string - "null" format: email phoneNumber: type: - string - "null" description: "If present, will be returned in e.164 format (example: +12065556666)" avatarUrl: type: - string - "null" format: uri description: "Recommended size: 100px x 100px, 1:1 aspect ratio; JPG, PNG, webp, or avif. Must start with https://" physicalAddress: oneOf: - $ref: "#/components/schemas/Address" - type: "null" mailingAddress: oneOf: - $ref: "#/components/schemas/Address" - type: "null" businessType: deprecated: true description: Deprecated. Use businessRepresentative instead. oneOf: - $ref: "#/components/schemas/BusinessTypeEnum" - type: "null" businessRepresentative: description: > When the user is a representative of a business or dealership, all vehicles and deals created by this user will automatically include the business information as the buyer or seller information. oneOf: - $ref: "#/components/schemas/EntityOwner" - type: "null" UserSummaryResponseBody: type: object required: - activated - buying - selling - deals properties: termsAccepted: type: boolean deprecated: true description: Deprecated. Use activated. This field will be removed. activated: type: boolean description: This value is true if a user with this referenceId has been added to KeySavvy using the createUser /user endpoint. selling: type: array items: $ref: "#/components/schemas/UserSummaryResponseBodySellingVehicle" description: > This array will contain an entry for every unique vehicle reference ID this user has been a part of as a seller. Each vehicle in this array will contain a "deals" array that includes an entry for each unique deal associated with the vehicle. buying: type: array items: $ref: "#/components/schemas/UserSummaryResponseBodyDeal" description: > A list of all deals that this user has indicated they would like to purchase. deals: type: array items: $ref: "#/components/schemas/UserSummaryResponseBodyDeal" deprecated: true description: > A list of all deals associated with this user. This field is deprecated and the newer `buying` and `selling` array should be used instead for more complete information. UserSummaryResponseBodySellingVehicle: type: object required: - vehicleReferenceId - vehicleUrl - vehicleDisplayId - marketplaceReferenceId - lienholderName - loan - lease - registrationState - vin - priceCents - year - make - model - color - deals - createdAt - updatedAt properties: 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 is recommended but not required to be unique. vehicleUrl: type: string format: uri description: > An absolute URL to the vehicle details page associated with this vehicle. Users should be sent to this page only until they have 1 or more active deals. Once a vehicle has deals, they should be directed to the specific deal details page whenever possible. The vehicle details page will continue to function throughout the deal lifecycle, but users may mistake it for their deal page and wonder why information is missing. marketplaceReferenceId: type: - string - "null" description: The marketplace reference ID associated with this vehicle. vin: type: string description: The Vehicle Identification Number of this vehicle. pattern: ^[A-Za-z0-9- ]{4,25}$ priceCents: type: - integer - "null" description: The price of this vehicle in cents. This value should only be displayed when the more specific deal priceCents is unavailable. 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. 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. 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). entityOwner: oneOf: - $ref: "#/components/schemas/EntityOwner" - type: "null" description: Vehicle ownership information. Indicates information about who owns the vehicle if it is not an individual. deals: type: array items: $ref: "#/components/schemas/UserSummaryResponseBodySellingVehicleDeal" description: A list of all deals associated with this vehicle. The user associated with this response will always be a seller on these deals. createdAt: type: string format: date-time description: ISO timestamp indicating when this vehicle was created. updatedAt: type: string format: date-time description: ISO timestamp indicating when this deal was last updated. UserSummaryResponseBodySellingVehicleDeal: type: object required: - status - dealReferenceId - marketplaceReferenceId - actionRequired - priceCents - dealUrl - createdAt - updatedAt properties: status: $ref: "#/components/schemas/DealStatusEnum" dealReferenceId: type: string description: The reference ID for this deal marketplaceReferenceId: type: - string - "null" description: The marketplace reference ID associated with this deal. 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. priceCents: type: - integer - "null" description: The base price of the vehicle displayed to the buyer and seller, excluding fees. Equal to sellerPriceCents and buyerPriceCents. 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. 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. 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. dealDisplayId: type: - string - "null" description: A user-visible ID for this deal. It is recommended but not required to be unique. 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. UserSummaryResponseBodyDeal: type: object required: - status - role - dealReferenceId - marketplaceReferenceId - actionRequired - dealUrl - vehicleReferenceId - vin - priceCents - year - make - model - color - createdAt - updatedAt properties: status: $ref: "#/components/schemas/DealStatusEnum" role: $ref: "#/components/schemas/DealRoleEnum" 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. dealReferenceId: type: string description: The reference ID for this deal marketplaceReferenceId: type: - string - "null" description: The marketplace reference ID associated with this deal. dealDisplayId: type: - string - "null" description: A user-visible ID for this deal. It is recommended but not required to be unique. 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. 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 is recommended but not required to be unique. lienholderName: type: - string - "null" description: The lienholder of this vehicle. Will only be included if the user being summarized is a seller on this deal. Can be null if there is no loan, or a seller has not yet provided this information. 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). buyerLenderName: type: - string - "null" description: The name of the buyers lender. Will only be included if the user being summarized is a buyer on this deal. Can be null if the buyer does not intend to finance or has not yet provided this information. vin: type: string description: The VIN of the vehicle associated with this deal. 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. year: type: - integer - "null" description: The year of the vehicle associated with this deal. Optional because year may be collected after a deal is created. make: type: - string - "null" description: The make of the vehicle associated with this deal. Optional because make may be collected after a deal is created. model: type: - string - "null" description: The model of the vehicle associated with this deal. Optional because vehicle may not have a model, or model may be collected after deal is created. color: type: - string - "null" description: Color of the vehicle. See VehicleColorEnum for examples. Additional colors may be added without versioning the API. 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. UserDocumentCreateRequestBody: type: object required: - documentType - file properties: documentType: type: string description: The type of document being uploaded. enum: - dealer-license file: type: string format: binary description: The document file being uploaded. This file must be an image (image/* or application/pdf mime-type). VehicleCreateRequestBody: type: object properties: sellerNonOwner: type: - boolean - "null" description: Indicates if the initial seller provided via sellerReferenceId is a non-owner, e.g. a consignment seller. default: false sellerReferenceId: type: string pattern: ^[a-zA-Z0-9_-]+$ description: ID that references the seller of the vehicle. This is the same as the referenceId used in /user vehicleReferenceId: type: string pattern: ^[a-zA-Z0-9_-]+$ description: > A stable, unique, case-sensitive partner-supplied ID for this vehicle. marketplaceReferenceId: type: - string - "null" description: The marketplace reference ID associated with this vehicle. displayId: type: string description: A user-visible ID for this vehicle. If it is not provided, no user-visible ID will be displayed. It can contain any characters, including whitespace. It is recommended but not required to be unique. vin: type: string description: | Vehicle Identification Number. Input will be sanitized by: 1. Removing invalid characters (alphanumeric only) 2. Converting to uppercase The resulting VIN must be 4-25 characters after sanitization. minLength: 4 maxLength: 25 priceCents: type: - integer - "null" description: Price of the vehicle in cents. 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: oneOf: - $ref: "#/components/schemas/VehicleColorEnum" - type: "null" 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). entityOwner: oneOf: - $ref: "#/components/schemas/EntityOwner" - type: "null" description: Vehicle ownership information. Indicates information about who owns the vehicle if it is not an individual. lienholderName: type: - string - "null" description: Name of the lienholder for the vehicle lienholderAccountNumber: type: - string - "null" description: Account number associated with the lienholder required: - sellerReferenceId - vehicleReferenceId - vin VehicleCreateResponseBody: type: object properties: referenceId: type: string pattern: ^[a-zA-Z0-9_-]+$ description: A stable, unique, case-sensitive ID that identifies this vehicle. If a vehicleReferenceId was provided in the request, this will be the same value. If no vehicleReferenceId was provided, partners should store this value for future reference. vehicleUrl: type: string format: uri description: > An absolute URL to the vehicle details page associated with this vehicle. Sellers should be sent to this page to proactively provide information about their vehicle before a buyer (and deal) exists. Once one or more deals exist, the more specific deal URL should be used in. marketplaceReferenceId: type: - string - "null" description: The marketplace reference ID associated with this vehicle. vin: type: string description: The standardized / sanitized Vehicle Identification Number of this vehicle. displayId: type: - string - "null" description: A user-visible ID for this vehicle. It can contain any characters, including whitespace. 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: Price of the vehicle in cents. 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 on it. 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). entityOwner: oneOf: - $ref: "#/components/schemas/EntityOwner" - type: "null" description: Vehicle ownership information. Indicates information about who owns the vehicle if it is not an individual. required: - referenceId - marketplaceReferenceId - vehicleUrl - vin VehicleDealCreateResponseBody: type: object properties: dealReferenceId: type: string pattern: ^[a-zA-Z0-9_-]+$ description: A stable, unique, case-sensitive ID that identifies this deal. If a dealReferenceId was provided in the request, this will be the same value. If no dealReferenceId was provided, partners should store this value for future reference. 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. required: - dealReferenceId - dealUrl VehicleDocumentCreateRequestBody: type: object required: - documentType - file properties: documentType: type: string description: The type of document being uploaded. enum: - title - title-back - registration - registration-back - vin-plate - odometer-photo - dealer-license - vehicle-inspection-report file: type: string format: binary description: The document file being uploaded. This file must be an image (image/* or application/pdf mime-type). BillOfLadingLinkRequestBody: type: object properties: onlineBillOfLadingUrl: type: string format: uri description: URL to the online bill of lading document transferMileage: type: integer description: Optional mileage at transfer required: - onlineBillOfLadingUrl BillOfLadingUploadRequestBody: type: object properties: transferMileage: type: integer description: Optional mileage at transfer. Must be specified before file. file: type: string description: BOL document file (image/* or application/pdf mime-type) format: binary required: - file VehicleDealCreateRequestBody: type: object properties: buyerReferenceId: type: string pattern: ^[a-zA-Z0-9_-]+$ description: ID that references the buyer of the vehicle. This is the same as the referenceId used in /user dealReferenceId: type: - string - "null" pattern: ^[a-zA-Z0-9_-]+$ description: A stable, unique, case-sensitive partner-supplied ID that identifies this deal. If this is not provided, KeySavvy will generate one for the deal. dealDisplayId: type: - string - "null" description: A user-visible ID for this deal. If it is not provided, no user-visible ID will be displayed. It can contain any characters, including whitespace. It is recommended but not required to be unique. 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. priceCents: type: - integer - "null" description: > The price the buyer and seller have agreed to, in cents. If this is not provided, KeySavvy will use the current vehicle price (if it exists). Existing deals that have not been reviewed & accepted by their buyer will reflect this updated price. required: - buyerReferenceId DealCreateRequestBody: type: object properties: sellerNonOwner: type: - boolean - "null" description: Indicates if the initial seller provided via sellerReferenceId is a non-owner, e.g. a consignment seller. default: false sellerReferenceId: type: string pattern: ^[a-zA-Z0-9_-]+$ description: ID that references the seller of the vehicle. This is the same as the referenceId used in /user buyerReferenceId: type: string pattern: ^[a-zA-Z0-9_-]+$ description: ID that references the buyer of the vehicle. This is the same as the referenceId used in /user vehicle: $ref: "#/components/schemas/DealCreateRequestBodyVehicle" referenceId: type: string pattern: ^[a-zA-Z0-9_-]+$ description: A stable, unique, case-sensitive partner-supplied ID that identifies this deal. displayId: type: - string - "null" description: A user-visible ID for this deal. If it is not provided, no user-visible ID will be displayed. It can contain any characters, including whitespace. It is recommended but not required to be unique. 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. required: - sellerReferenceId - buyerReferenceId - vehicle - referenceId DealCreateRequestBodyVehicle: type: object properties: referenceId: type: string pattern: ^[a-zA-Z0-9_-]+$ description: > A stable, unique, case-sensitive partner-supplied ID for this vehicle. If an existing vehicle exists with this referenceId, the VIN must be identical, and the sellerReferenceId of the deal must be associated with the existing vehicle, otherwise a 409 will be returned. When the vehicle already exists, no vehicle data will be changed (displayId, year, make, and model will be ignored). If referenceId is provided but does not exist, a new vehicle will be created with the referenceId and other vehicle data in the request. If no referenceId is provided, the vehicle will be created if the seller does not already have a vehicle with the same VIN (otherwise, the existing vehicle will be reused). displayId: type: - string - "null" description: A user-visible ID for this vehicle. If it is not provided, no user-visible ID will be displayed. It can contain any characters, including whitespace. It is recommended but not required to be unique. marketplaceReferenceId: type: - string - "null" description: The marketplace reference ID associated with this vehicle and deal. vin: type: string description: | Vehicle Identification Number. Input will be sanitized by: 1. Removing invalid characters (alphanumeric only) 2. Converting to uppercase The resulting VIN must be 4-25 characters after sanitization. minLength: 4 maxLength: 25 priceCents: type: integer description: The price the buyer and seller have agreed to, in cents. year: type: integer description: Year of the vehicle make: type: string description: Make of the vehicle model: type: string description: Model of the vehicle color: oneOf: - $ref: "#/components/schemas/VehicleColorEnum" - type: "null" 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). entityOwner: oneOf: - $ref: "#/components/schemas/EntityOwner" - type: "null" description: Vehicle ownership information. Indicates information about who owns the vehicle if it is not an individual. lienholderName: type: - string - "null" description: Name of the lienholder for the vehicle lienholderAccountNumber: type: - string - "null" description: Account number associated with the lienholder required: - vin VehicleDetailsResponseBody: type: object properties: vehicleReferenceId: type: string pattern: ^[a-zA-Z0-9_-]+$ description: A stable, unique, case-sensitive partner-supplied ID that identifies this vehicle. vehicleDisplayId: type: - string - "null" description: A user-visible ID for this vehicle. It can contain any characters, including whitespace. marketplaceReferenceId: type: - string - "null" description: The marketplace reference ID associated with this vehicle. vehicleUrl: type: string format: uri description: > An absolute URL to the vehicle details page associated with this vehicle. Users should be sent to this page only until they have 1 or more active deals. Once a vehicle has deals, they should be directed to the specific deal details page whenever possible. The vehicle details page will continue to function throughout the deal lifecycle, but users may mistake it for their deal page and wonder why information is missing. sellerReferenceIds: description: List of user reference IDs acting as sellers of this vehicle. Sellers are not necessarily owners on the title of the vehicle. type: array items: type: string vin: type: string description: Vehicle Identification Number 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 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: The price of this vehicle in cents. This value should only be displayed when the more specific deal priceCents is unavailable. transactionFees: $ref: "#/components/schemas/TransactionFees" description: > Transaction fees associated with this vehicle. These are the values intended for display *prior to deal creation*. Once available, the `transactionFees` field on the deal object should always be displayed with priority over the information in this field. 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). entityOwner: oneOf: - $ref: "#/components/schemas/EntityOwner" - type: "null" description: Vehicle ownership information. Indicates information about who owns the vehicle if it is not an individual. deals: description: List of deals associated with this vehicle. type: array items: $ref: "#/components/schemas/VehicleDetailsResponseBodyDeal" createdAt: type: string format: date-time description: ISO timestamp indicating when this vehicle was created. updatedAt: type: string format: date-time description: ISO timestamp indicating when this vehicle was last updated. required: - vehicleReferenceId - vehicleDisplayId - marketplaceReferenceId - vehicleUrl - sellerReferenceIds - lienholderName - loan - lease - registrationState - vin - priceCents - transactionFees - deals - createdAt - updatedAt VehicleDetailsResponseBodyDeal: type: object properties: dealReferenceId: type: string pattern: ^[a-zA-Z0-9_-]+$ description: A stable, unique, case-sensitive partner-supplied ID that identifies this deal. dealDisplayId: type: - string - "null" description: A user-visible ID for this deal. It can contain any characters, including whitespace. marketplaceReferenceId: type: - string - "null" description: The marketplace reference ID associated with this deal. vehicleReferenceId: type: string pattern: ^[a-zA-Z0-9_-]+$ description: A stable, unique, case-sensitive partner-supplied ID that identifies this vehicle. vehicleDisplayId: type: - string - "null" description: A user-visible ID for this vehicle. 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. 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. 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: List of users with a BUYER role on this deal. type: array items: $ref: "#/components/schemas/UserWithDealStatus" 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. priceCents: type: - integer - "null" description: The base price of the vehicle displayed to the buyer and seller, excluding fees. Equal to sellerPriceCents and buyerPriceCents. 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" paymentVerifiedAt: type: - string - "null" format: date-time description: ISO timestamp indicating when payment was verified. transferConfirmedAt: type: - string - "null" format: date-time description: ISO timestamp indicating when the vehicle was picked up. titleSentAt: type: - string - "null" format: date-time description: ISO timestamp indicating when the title was sent to the buyer. 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. required: - dealReferenceId - dealDisplayId - marketplaceReferenceId - displayTitle - dealUrl - status - statusDescription - sellers - buyers - transactionFees - vehicleReferenceId - vehicleDisplayId - createdAt - updatedAt 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: List of users with a BUYER role on this deal. 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. 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. 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). 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 - dealUrl - vehicleReferenceId - vehicleDisplayId - vin - year - make - model - color - priceCents - transactionFees - 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. ErrorResponseBody: type: object properties: error: type: string message: type: string CancelDealConflictErrorResponseBody: type: object properties: error: type: string enum: - DEAL_CANCELED - TRANSFER_COMPLETE - BUYER_NOT_REFUNDED - PAYMENT_VERIFIED message: type: string AcceptedResponseBody: type: object properties: message: type: string CreatedResponseBody: type: object properties: message: type: string UpdatedResponseBody: type: object properties: message: type: string securitySchemes: apiKey: type: apiKey in: header name: keysavvy-api security: - apiKey: []