BeneficialOwner

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/lightspark/main/json-schema/lightspark-beneficial-owner-schema.json",
  "title": "BeneficialOwner",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/lightspark-kyc-kyb-verifications-api-openapi.yml#/components/schemas/BeneficialOwner",
  "type": "object",
  "required": [
    "id",
    "customerId",
    "roles",
    "ownershipPercentage",
    "personalInfo",
    "kycStatus",
    "createdAt"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for this beneficial owner"
    },
    "customerId": {
      "type": "string",
      "description": "The ID of the business customer this beneficial owner is associated with"
    },
    "roles": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/BeneficialOwnerRole"
      },
      "description": "Roles of this person within the business"
    },
    "ownershipPercentage": {
      "type": "integer",
      "description": "Percentage of ownership in the business (0-100)",
      "minimum": 0,
      "maximum": 100
    },
    "personalInfo": {
      "$ref": "#/$defs/BeneficialOwnerPersonalInfo"
    },
    "kycStatus": {
      "$ref": "#/$defs/KycStatus"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "When this beneficial owner was created"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "When this beneficial owner was last updated"
    }
  },
  "$defs": {
    "Address": {
      "type": "object",
      "required": [
        "line1",
        "postalCode",
        "country"
      ],
      "properties": {
        "line1": {
          "type": "string",
          "description": "Street address line 1"
        },
        "line2": {
          "type": "string",
          "description": "Street address line 2"
        },
        "city": {
          "type": "string",
          "description": "City"
        },
        "state": {
          "type": "string",
          "description": "State/Province/Region"
        },
        "postalCode": {
          "type": "string",
          "description": "Postal/ZIP code"
        },
        "country": {
          "type": "string",
          "description": "Country code (ISO 3166-1 alpha-2)"
        }
      }
    },
    "BeneficialOwnerPersonalInfo": {
      "type": "object",
      "required": [
        "firstName",
        "lastName",
        "birthDate",
        "nationality",
        "address",
        "idType",
        "identifier"
      ],
      "properties": {
        "firstName": {
          "type": "string",
          "description": "First name of the individual"
        },
        "middleName": {
          "type": "string",
          "description": "Middle name of the individual"
        },
        "lastName": {
          "type": "string",
          "description": "Last name of the individual"
        },
        "birthDate": {
          "type": "string",
          "format": "date",
          "description": "Date of birth in ISO 8601 format (YYYY-MM-DD)"
        },
        "nationality": {
          "type": "string",
          "description": "Country of nationality (ISO 3166-1 alpha-2)"
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Email address of the individual"
        },
        "phoneNumber": {
          "type": "string",
          "description": "Phone number in E.164 format",
          "pattern": "^\\+[1-9]\\d{1,14}$"
        },
        "address": {
          "$ref": "#/$defs/Address"
        },
        "idType": {
          "$ref": "#/$defs/IdentificationType"
        },
        "identifier": {
          "type": "string",
          "description": "The identification number or value"
        },
        "countryOfIssuance": {
          "type": "string",
          "description": "Country that issued the identification (ISO 3166-1 alpha-2)"
        }
      }
    },
    "BeneficialOwnerRole": {
      "type": "string",
      "enum": [
        "UBO",
        "DIRECTOR",
        "COMPANY_OFFICER",
        "CONTROL_PERSON",
        "TRUSTEE",
        "GENERAL_PARTNER"
      ],
      "description": "Role of the beneficial owner within the business"
    },
    "IdentificationType": {
      "type": "string",
      "enum": [
        "SSN",
        "ITIN",
        "EIN",
        "NON_US_TAX_ID"
      ],
      "description": "Type of tax identification"
    },
    "KycStatus": {
      "type": "string",
      "enum": [
        "UNVERIFIED",
        "PENDING",
        "APPROVED",
        "REJECTED",
        "HOLD"
      ],
      "description": "The current KYC status of a customer. `HOLD` means the customer is placed on hold and may be required to update or provide more information."
    }
  }
}