DealCreateRequestBody

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/keysavvy/main/json-schema/keysavvy-deal-create-request-body-schema.json",
  "title": "DealCreateRequestBody",
  "x-generated": "2026-10-25",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/keysavvy-openapi.json#/components/schemas/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": "#/$defs/DealCreateRequestBodyVehicle"
    },
    "referenceId": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[a-zA-Z0-9_-]+$",
      "description": "A stable, unique, case-sensitive partner-supplied ID that identifies this deal.\nIf explicitly set to null, a reference ID will be automatically assigned and returned in the `dealReferenceId` field of the response.\n"
    },
    "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."
    },
    "price": {
      "$ref": "#/$defs/Price",
      "description": "Pricing configuration for the deal. Use 'SplitPrice' type for different buyer/seller prices, or 'SinglePrice' type for a single agreed price."
    },
    "buyerAccepted": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "When true, the deal will be created with buyer acceptance already set, indicating the price has been agreed upon externally. The seller must still accept the deal in KeySavvy. This flag must be enabled for your platform. Contact us to enable this feature."
    },
    "postPickupInspectionRequired": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "When true, the deal will require post-pickup inspection approval before transfer is completed. This flag must be enabled for your platform. Contact us to enable this feature. Without it, true or false is rejected with a 403."
    },
    "entityBuyer": {
      "oneOf": [
        {
          "$ref": "#/$defs/EntityOwnerCreateRequest"
        },
        {
          "type": "null"
        }
      ],
      "description": "Omitted: organization defaults, or buyer profile when no organization. With an organization, null or missing defaults creates a business buyer without details; without one, null means no business buyer.\n"
    },
    "buyerOrganizationReferenceId": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[a-zA-Z0-9_-]+$",
      "description": "Required for current or former members; buyer must be an active member. New users join automatically. Unknown ID: 400; membership conflicts: 409.\n"
    }
  },
  "required": [
    "sellerReferenceId",
    "buyerReferenceId",
    "vehicle",
    "referenceId"
  ],
  "$defs": {
    "AddressRequest": {
      "type": "object",
      "description": "Empty strings are treated as unspecified. Addresses are standardized and validated where possible, so a later read may differ from what was sent.\n",
      "properties": {
        "line1": {
          "type": "string"
        },
        "line2": {
          "type": [
            "string",
            "null"
          ]
        },
        "city": {
          "type": "string"
        },
        "state": {
          "type": "string",
          "description": "Two-letter code. A full state or territory name is also accepted, and a code that disagrees with the rest of the address is corrected when the address validates.\n"
        },
        "zip": {
          "type": "string",
          "description": "For US addresses, should be 5 digits. Accepts Zip+4, but prefer zip4.\n"
        },
        "zip4": {
          "type": [
            "string",
            "null"
          ],
          "description": "Ignored for non-US addresses."
        },
        "country": {
          "type": "string",
          "description": "Only \"US\" is supported"
        }
      },
      "required": [
        "line1",
        "city",
        "state",
        "zip",
        "country"
      ]
    },
    "DealCreateRequestBodyVehicle": {
      "type": "object",
      "properties": {
        "referenceId": {
          "type": [
            "string",
            "null"
          ],
          "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).\n"
        },
        "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:\n1. Removing invalid characters (alphanumeric only)\n2. Converting to uppercase\nThe resulting VIN must be 4-25 characters after sanitization.\n",
          "minLength": 4,
          "maxLength": 25
        },
        "priceCents": {
          "type": "integer",
          "minimum": 100,
          "maximum": 99999900,
          "description": "The price the buyer and seller have agreed to, in cents."
        },
        "year": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Year of the vehicle, from 1885 to 2 years in the future. An out-of-range year is dropped, and the vehicle is saved without it. For standard VINs the year is decoded from the VIN."
        },
        "make": {
          "type": [
            "string",
            "null"
          ],
          "description": "Make of the vehicle. Only printable ASCII characters (0x20-0x7E) are accepted. Common look-alikes (smart quotes, en/em/non-breaking dashes, accented Latin letters) are mapped to their closest ASCII equivalent; any remaining unsupported characters (emoji, control chars, zero-width chars, non-Latin scripts) are removed. If the resulting value is empty, it will be removed."
        },
        "model": {
          "type": [
            "string",
            "null"
          ],
          "description": "Model of the vehicle. Only printable ASCII characters (0x20-0x7E) are accepted. Common look-alikes (smart quotes, en/em/non-breaking dashes, accented Latin letters) are mapped to their closest ASCII equivalent; any remaining unsupported characters (emoji, control chars, zero-width chars, non-Latin scripts) are removed. If the resulting value is empty, it will be removed."
        },
        "color": {
          "oneOf": [
            {
              "$ref": "#/$defs/VehicleColorEnum"
            },
            {
              "type": "null"
            }
          ]
        },
        "loan": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Indicates if the vehicle has a loan on it. A lienholderName or lienholderAccountNumber means the vehicle has a loan, whatever this is set to. When null or omitted without lienholder details, the seller is asked whether the vehicle has a loan."
        },
        "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": "#/$defs/EntityOwnerCreateRequest"
            },
            {
              "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"
        },
        "standardizedVehicleType": {
          "oneOf": [
            {
              "$ref": "#/$defs/VehicleTypeEnum"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional standardized vehicle type. Used only when KeySavvy cannot determine the vehicle type from the VIN, for example non-standard or collector VINs and incomplete or conversion vehicles. Otherwise it is ignored. When it is used, the value is stored and returned on the vehicle response; when it is ignored, that field is null.\n"
        }
      },
      "required": [
        "vin"
      ]
    },
    "EntityOwnerCreateRequest": {
      "type": "object",
      "properties": {
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "address": {
          "description": "Default for physicalAddress and mailingAddress. Complete addresses supplied separately take precedence. Unusable addresses are ignored.\n",
          "oneOf": [
            {
              "$ref": "#/$defs/AddressRequest"
            },
            {
              "type": "null"
            }
          ]
        },
        "physicalAddress": {
          "oneOf": [
            {
              "$ref": "#/$defs/AddressRequest"
            },
            {
              "type": "null"
            }
          ]
        },
        "mailingAddress": {
          "oneOf": [
            {
              "$ref": "#/$defs/AddressRequest"
            },
            {
              "type": "null"
            }
          ]
        },
        "ownerType": {
          "type": "string",
          "enum": [
            "business",
            "dealer"
          ]
        },
        "dealerLicenseState": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^[A-Z]{2}$",
          "description": "Two-letter US license state or territory; ignored unless ownerType is dealer. Invalid code: 400.\n"
        }
      },
      "required": [
        "ownerType"
      ]
    },
    "Price": {
      "type": "object",
      "required": [
        "type"
      ],
      "oneOf": [
        {
          "$ref": "#/$defs/SplitPrice"
        },
        {
          "$ref": "#/$defs/SinglePrice"
        }
      ]
    },
    "SinglePrice": {
      "description": "Pricing configuration where the buyer and seller have agreed to a single price.",
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "SinglePrice"
        },
        "priceCents": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 100,
          "maximum": 99999900,
          "description": "The price the buyer and seller have agreed to, in cents."
        }
      },
      "required": [
        "type"
      ]
    },
    "SplitPrice": {
      "description": "Pricing configuration where the buyer and seller amounts are configured independently. In this pricing model the amounts are managed exclusively via the API, rather than by the seller.",
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "SplitPrice"
        },
        "buyerPriceCents": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 100,
          "maximum": 99999900,
          "description": "The price the buyer will pay, in cents."
        },
        "sellerPriceCents": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 100,
          "maximum": 99999900,
          "description": "The price the seller will receive, in cents."
        }
      },
      "required": [
        "type"
      ]
    },
    "VehicleColorEnum": {
      "type": "string",
      "enum": [
        "BLACK",
        "BLUE",
        "BROWN",
        "GOLD",
        "GRAY",
        "GREEN",
        "ORANGE",
        "PINK",
        "PURPLE",
        "RED",
        "SILVER",
        "WHITE",
        "YELLOW"
      ],
      "description": "The approximate color of the vehicle."
    },
    "VehicleTypeEnum": {
      "type": "string",
      "enum": [
        "CAR_SUV",
        "PICKUP",
        "VAN",
        "MOTORHOME",
        "MOTORCYCLE",
        "COMMERCIAL_TRUCK",
        "PICKUP_GT_1_TON",
        "BUS",
        "ATV",
        "TRAILER",
        "OTHER"
      ],
      "description": "The standardized KeySavvy vehicle type."
    }
  }
}