VehicleCreateRequestBody

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/keysavvy/main/json-schema/keysavvy-vehicle-create-request-body-schema.json",
  "title": "VehicleCreateRequestBody",
  "x-generated": "2026-10-25",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/keysavvy-openapi.json#/components/schemas/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",
        "null"
      ],
      "pattern": "^[a-zA-Z0-9_-]+$",
      "description": "A stable, unique, case-sensitive partner-supplied ID for this vehicle.\nIf explicitly set to null, a reference ID will be automatically assigned and returned in the `referenceId` field of the response.\n"
    },
    "marketplaceReferenceId": {
      "type": [
        "string",
        "null"
      ],
      "description": "The marketplace reference ID associated with this vehicle."
    },
    "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."
    },
    "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",
        "null"
      ],
      "minimum": 100,
      "maximum": 99999900,
      "description": "Price of the vehicle 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": [
    "sellerReferenceId",
    "vehicleReferenceId",
    "vin"
  ],
  "$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"
      ]
    },
    "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"
      ]
    },
    "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."
    }
  }
}