{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/lightspark/main/json-schema/lightspark-beneficial-owner-list-response-schema.json",
  "title": "BeneficialOwnerListResponse",
  "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/BeneficialOwnerListResponse",
  "type": "object",
  "required": [
    "data",
    "hasMore"
  ],
  "properties": {
    "data": {
      "type": "array",
      "description": "List of beneficial owners matching the filter criteria",
      "items": {
        "$ref": "#/$defs/BeneficialOwner"
      }
    },
    "hasMore": {
      "type": "boolean",
      "description": "Indicates if more results are available beyond this page"
    },
    "nextCursor": {
      "type": "string",
      "description": "Cursor to retrieve the next page of results (only present if hasMore is true)"
    },
    "totalCount": {
      "type": "integer",
      "description": "Total number of results matching the criteria"
    }
  },
  "$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)"
        }
      }
    },
    "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"
        }
      }
    },
    "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."
    }
  }
}