VehicleDealCreateRequestBody

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/keysavvy/main/json-schema/keysavvy-vehicle-deal-create-request-body-schema.json",
  "title": "VehicleDealCreateRequestBody",
  "x-generated": "2026-10-25",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/keysavvy-openapi.json#/components/schemas/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"
      ],
      "minimum": 100,
      "maximum": 99999900,
      "description": "The price the buyer and seller have agreed to, in cents. If this is not provided, KeySavvy will use the\ncurrent vehicle price (if it exists). Existing deals that have not been reviewed & accepted by their buyer\nwill reflect this updated price.\n"
    },
    "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": [
    "buyerReferenceId"
  ],
  "$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"
      ]
    },
    "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"
      ]
    }
  }
}