{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/keysavvy/main/json-schema/keysavvy-user-create-request-body-schema.json",
  "title": "UserCreateRequestBody",
  "x-generated": "2026-10-25",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/keysavvy-openapi.json#/components/schemas/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",
        "null"
      ]
    },
    "lastName": {
      "type": [
        "string",
        "null"
      ]
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "Email addresses are sanitized (common typos are corrected, e.g. gmail.con -> gmail.com) and lowercased."
    },
    "physicalAddress": {
      "description": "The user's residential address. Determines the state a purchased vehicle is registered in. An incomplete or unusable address is ignored.\n",
      "oneOf": [
        {
          "$ref": "#/$defs/AddressRequest"
        },
        {
          "type": "null"
        }
      ]
    },
    "mailingAddress": {
      "description": "The address where the user receives mail. An incomplete or unusable address is ignored.\n",
      "oneOf": [
        {
          "$ref": "#/$defs/AddressRequest"
        },
        {
          "type": "null"
        }
      ]
    },
    "phoneNumber": {
      "type": [
        "string",
        "null"
      ],
      "description": "Only US and Canada NANP numbers are supported. E.164 format is preferred, e.g. +15551234567. Parsing is lenient: other US-style numbers such as (555) 123-4567 are tolerated and normalized to E.164.\n"
    },
    "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. When null or omitted, the deprecated businessType applies. Null without a businessType removes the business representative and keeps the stored business name and address.\n",
      "oneOf": [
        {
          "$ref": "#/$defs/EntityOwnerCreateRequest"
        },
        {
          "type": "null"
        }
      ]
    },
    "businessType": {
      "deprecated": true,
      "description": "Deprecated. Use businessRepresentative instead.",
      "oneOf": [
        {
          "$ref": "#/$defs/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://"
    },
    "organizationReferenceId": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[a-zA-Z0-9_-]+$",
      "description": "Joins when creating or activating the user. Existing users: POST /organization/{referenceId}/users. Unknown ID: 400; ineligible membership rejects the request (409).\n"
    }
  },
  "required": [
    "referenceId",
    "email"
  ],
  "$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"
      ]
    },
    "BusinessTypeEnum": {
      "type": "string",
      "enum": [
        "dealer"
      ],
      "description": "Indicates if the user is a business. Supports 'dealer' for automotive dealers."
    },
    "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"
      ]
    }
  }
}