CustomerListResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/lightspark/main/json-schema/lightspark-customer-list-response-schema.json",
  "title": "CustomerListResponse",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/lightspark-customers-api-openapi.yml#/components/schemas/CustomerListResponse",
  "type": "object",
  "required": [
    "data",
    "hasMore"
  ],
  "properties": {
    "data": {
      "type": "array",
      "description": "List of customers matching the filter criteria",
      "items": {
        "$ref": "#/$defs/CustomerOneOf"
      }
    },
    "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 customers matching the criteria (excluding pagination)"
    }
  },
  "$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"
    },
    "BusinessCustomer": {
      "title": "Business Customer",
      "allOf": [
        {
          "$ref": "#/$defs/Customer"
        },
        {
          "$ref": "#/$defs/BusinessCustomerFields"
        },
        {
          "type": "object",
          "properties": {
            "businessInfo": {
              "$ref": "#/$defs/BusinessInfoResponse"
            },
            "beneficialOwners": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/BeneficialOwner"
              }
            }
          }
        }
      ]
    },
    "BusinessCustomerFields": {
      "type": "object",
      "required": [
        "customerType"
      ],
      "properties": {
        "customerType": {
          "type": "string",
          "enum": [
            "BUSINESS"
          ]
        },
        "kybStatus": {
          "$ref": "#/$defs/KybStatus"
        },
        "address": {
          "$ref": "#/$defs/Address"
        },
        "businessInfo": {
          "$ref": "#/$defs/BusinessInfoUpdate"
        }
      }
    },
    "BusinessInfoResponse": {
      "type": "object",
      "description": "Business information returned on a customer. `taxId` and `incorporatedOn` are\nrequired on creation but may be absent on legacy customers that pre-date the\nrequirement, so both are optional in responses.\n",
      "required": [
        "legalName"
      ],
      "properties": {
        "legalName": {
          "type": "string",
          "description": "Legal name of the business"
        },
        "doingBusinessAs": {
          "type": "string",
          "description": "Trade name or DBA name of the business, if different from the legal name"
        },
        "country": {
          "type": "string",
          "description": "Country of incorporation or registration (ISO 3166-1 alpha-2)"
        },
        "registrationNumber": {
          "type": "string",
          "description": "Business registration number"
        },
        "incorporatedOn": {
          "type": "string",
          "format": "date",
          "description": "Date of incorporation in ISO 8601 format (YYYY-MM-DD)"
        },
        "entityType": {
          "$ref": "#/$defs/EntityType"
        },
        "taxId": {
          "type": "string",
          "description": "Tax identification number"
        },
        "countriesOfOperation": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of countries where the business operates (ISO 3166-1 alpha-2)"
        },
        "businessType": {
          "$ref": "#/$defs/BusinessType"
        },
        "purposeOfAccount": {
          "$ref": "#/$defs/PurposeOfAccount"
        },
        "sourceOfFunds": {
          "type": "string",
          "description": "The primary source of funds for the business"
        },
        "expectedMonthlyTransactionCount": {
          "type": "string",
          "enum": [
            "COUNT_UNDER_10",
            "COUNT_10_TO_100",
            "COUNT_100_TO_500",
            "COUNT_500_TO_1000",
            "COUNT_OVER_1000"
          ],
          "description": "Expected number of transactions per month"
        },
        "expectedMonthlyTransactionVolume": {
          "type": "string",
          "enum": [
            "VOLUME_UNDER_10K",
            "VOLUME_10K_TO_100K",
            "VOLUME_100K_TO_1M",
            "VOLUME_1M_TO_10M",
            "VOLUME_OVER_10M"
          ],
          "description": "Expected total transaction volume per month in USD equivalent"
        },
        "expectedRecipientJurisdictions": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of countries where the business expects to send payments (ISO 3166-1 alpha-2)"
        },
        "naicsCode": {
          "type": "string",
          "pattern": "^\\d{2,6}$",
          "description": "NAICS code describing the nature of the business (2-6 digits)"
        },
        "sourceOfFundsCategories": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/SourceOfFundsCategory"
          },
          "description": "Structured source-of-funds categories for the business"
        },
        "sourceOfFundsOtherDescription": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500,
          "description": "Description of the source of funds when OTHER is selected"
        },
        "purposeOfAccountOtherDescription": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500,
          "description": "Description of the account purpose when OTHER is selected"
        },
        "expectedCounterpartyCountries": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of countries of the business's expected transaction counterparties (ISO 3166-1 alpha-2)"
        }
      }
    },
    "BusinessInfoUpdate": {
      "type": "object",
      "description": "Additional information for business entities",
      "properties": {
        "legalName": {
          "type": "string",
          "description": "Legal name of the business"
        },
        "doingBusinessAs": {
          "type": "string",
          "description": "Trade name or DBA name of the business, if different from the legal name"
        },
        "country": {
          "type": "string",
          "description": "Country of incorporation or registration (ISO 3166-1 alpha-2)"
        },
        "registrationNumber": {
          "type": "string",
          "description": "Business registration number"
        },
        "incorporatedOn": {
          "type": "string",
          "format": "date",
          "description": "Date of incorporation in ISO 8601 format (YYYY-MM-DD)"
        },
        "entityType": {
          "$ref": "#/$defs/EntityType"
        },
        "taxId": {
          "type": "string",
          "description": "Tax identification number"
        },
        "countriesOfOperation": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of countries where the business operates (ISO 3166-1 alpha-2)"
        },
        "businessType": {
          "$ref": "#/$defs/BusinessType"
        },
        "purposeOfAccount": {
          "$ref": "#/$defs/PurposeOfAccount"
        },
        "sourceOfFunds": {
          "type": "string",
          "description": "The primary source of funds for the business"
        },
        "expectedMonthlyTransactionCount": {
          "type": "string",
          "enum": [
            "COUNT_UNDER_10",
            "COUNT_10_TO_100",
            "COUNT_100_TO_500",
            "COUNT_500_TO_1000",
            "COUNT_OVER_1000"
          ],
          "description": "Expected number of transactions per month"
        },
        "expectedMonthlyTransactionVolume": {
          "type": "string",
          "enum": [
            "VOLUME_UNDER_10K",
            "VOLUME_10K_TO_100K",
            "VOLUME_100K_TO_1M",
            "VOLUME_1M_TO_10M",
            "VOLUME_OVER_10M"
          ],
          "description": "Expected total transaction volume per month in USD equivalent"
        },
        "expectedRecipientJurisdictions": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of countries where the business expects to send payments (ISO 3166-1 alpha-2)"
        },
        "naicsCode": {
          "type": "string",
          "pattern": "^\\d{2,6}$",
          "description": "NAICS code describing the nature of the business (2-6 digits)"
        },
        "sourceOfFundsCategories": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/SourceOfFundsCategory"
          },
          "description": "Structured source-of-funds categories for the business"
        },
        "sourceOfFundsOtherDescription": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500,
          "description": "Description of the source of funds when OTHER is selected"
        },
        "purposeOfAccountOtherDescription": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500,
          "description": "Description of the account purpose when OTHER is selected"
        },
        "expectedCounterpartyCountries": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of countries of the business's expected transaction counterparties (ISO 3166-1 alpha-2)"
        }
      }
    },
    "BusinessType": {
      "type": "string",
      "description": "The high-level industry category of the business",
      "enum": [
        "AGRICULTURE_FORESTRY_FISHING_AND_HUNTING",
        "MINING_QUARRYING_AND_OIL_AND_GAS_EXTRACTION",
        "UTILITIES",
        "CONSTRUCTION",
        "MANUFACTURING",
        "WHOLESALE_TRADE",
        "RETAIL_TRADE",
        "TRANSPORTATION_AND_WAREHOUSING",
        "INFORMATION",
        "FINANCE_AND_INSURANCE",
        "REAL_ESTATE_AND_RENTAL_AND_LEASING",
        "PROFESSIONAL_SCIENTIFIC_AND_TECHNICAL_SERVICES",
        "MANAGEMENT_OF_COMPANIES_AND_ENTERPRISES",
        "ADMINISTRATIVE_AND_SUPPORT_AND_WASTE_MANAGEMENT_AND_REMEDIATION_SERVICES",
        "EDUCATIONAL_SERVICES",
        "HEALTH_CARE_AND_SOCIAL_ASSISTANCE",
        "ARTS_ENTERTAINMENT_AND_RECREATION",
        "ACCOMMODATION_AND_FOOD_SERVICES",
        "OTHER_SERVICES",
        "PUBLIC_ADMINISTRATION"
      ]
    },
    "ContactVerification": {
      "type": "object",
      "description": "Email and/or phone verification state for the customer. This object is **only present when the customer's regulatory jurisdiction requires contact verification** (e.g. EU customers). For customers who have no such requirement, this object is omitted entirely — no action is needed.\n\nEach channel is reported independently: only the channels the customer's provider actually requires are present. A provider may require both email and phone, just one of them, or — when the object is absent — neither. Every channel that **is** present must reach `VERIFIED` before the customer can begin KYC. Drive each present channel with `POST /customers/{customerId}/verify-email` and/or `POST /customers/{customerId}/verify-phone` (and their `/confirm` sub-routes).",
      "properties": {
        "email": {
          "$ref": "#/$defs/ContactVerificationStatus",
          "description": "Verification status of the customer's email address. Present only when the provider requires email verification."
        },
        "phone": {
          "$ref": "#/$defs/ContactVerificationStatus",
          "description": "Verification status of the customer's phone number. Present only when the provider requires phone verification."
        }
      }
    },
    "ContactVerificationStatus": {
      "type": "string",
      "description": "Status of an individual contact-verification channel (email or phone). `PENDING` means verification is required but not yet completed; `VERIFIED` means the channel has been confirmed.",
      "enum": [
        "PENDING",
        "VERIFIED"
      ]
    },
    "Customer": {
      "type": "object",
      "required": [
        "umaAddress",
        "platformCustomerId",
        "customerType"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "System-generated unique identifier",
          "readOnly": true
        },
        "platformCustomerId": {
          "type": "string",
          "description": "Platform-specific customer identifier"
        },
        "customerType": {
          "$ref": "#/$defs/CustomerType"
        },
        "region": {
          "type": "string",
          "description": "Country code (ISO 3166-1 alpha-2) representing the customer's regional identity and regulatory jurisdiction."
        },
        "currencies": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of currency codes enabled for this customer."
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Email address for the customer."
        },
        "phoneNumber": {
          "type": "string",
          "pattern": "^\\+[1-9]\\d{1,14}$",
          "description": "Phone number for the customer in strict E.164 format."
        },
        "umaAddress": {
          "type": "string",
          "description": "Full UMA address (always present in responses, even if system-generated). This is an optional identifier to route payments to the customer."
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "description": "Creation timestamp",
          "readOnly": true
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "Last update timestamp",
          "readOnly": true
        },
        "isDeleted": {
          "type": "boolean",
          "description": "Whether the customer is marked as deleted",
          "readOnly": true
        },
        "contactVerification": {
          "allOf": [
            {
              "$ref": "#/$defs/ContactVerification"
            }
          ],
          "readOnly": true,
          "description": "Email and phone verification state. **Only present when the customer's payment provider requires it** (e.g. EU customers); omitted otherwise."
        }
      }
    },
    "CustomerOneOf": {
      "oneOf": [
        {
          "$ref": "#/$defs/IndividualCustomer"
        },
        {
          "$ref": "#/$defs/BusinessCustomer"
        }
      ]
    },
    "CustomerType": {
      "type": "string",
      "enum": [
        "INDIVIDUAL",
        "BUSINESS"
      ],
      "description": "Whether the customer is an individual or a business entity"
    },
    "EntityType": {
      "type": "string",
      "enum": [
        "SOLE_PROPRIETORSHIP",
        "PARTNERSHIP",
        "LLC",
        "CORPORATION",
        "S_CORPORATION",
        "NON_PROFIT",
        "OTHER"
      ],
      "description": "Legal entity type of the business"
    },
    "IdentificationType": {
      "type": "string",
      "enum": [
        "SSN",
        "ITIN",
        "EIN",
        "NON_US_TAX_ID"
      ],
      "description": "Type of tax identification"
    },
    "IndividualCustomer": {
      "title": "Individual Customer",
      "allOf": [
        {
          "$ref": "#/$defs/Customer"
        },
        {
          "$ref": "#/$defs/IndividualCustomerFields"
        }
      ]
    },
    "IndividualCustomerFields": {
      "type": "object",
      "required": [
        "customerType"
      ],
      "properties": {
        "customerType": {
          "type": "string",
          "enum": [
            "INDIVIDUAL"
          ]
        },
        "kycStatus": {
          "$ref": "#/$defs/KycStatus"
        },
        "fullName": {
          "type": "string",
          "description": "Individual's full name"
        },
        "birthDate": {
          "type": "string",
          "format": "date",
          "description": "Date of birth in ISO 8601 format (YYYY-MM-DD)"
        },
        "nationality": {
          "type": "string",
          "description": "Country code (ISO 3166-1 alpha-2)"
        },
        "address": {
          "$ref": "#/$defs/Address"
        }
      }
    },
    "KybStatus": {
      "type": "string",
      "enum": [
        "UNVERIFIED",
        "PENDING",
        "APPROVED",
        "REJECTED",
        "HOLD"
      ],
      "description": "The current KYB status of a business customer. `HOLD` means the customer is placed on hold and may be required to update or provide more information."
    },
    "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."
    },
    "PurposeOfAccount": {
      "type": "string",
      "enum": [
        "CONTRACTOR_PAYOUTS",
        "CREATOR_PAYOUTS",
        "EMPLOYEE_PAYOUTS",
        "MARKETPLACE_SELLER_PAYOUTS",
        "SUPPLIER_PAYMENTS",
        "CROSS_BORDER_B2B",
        "AR_AUTOMATION",
        "AP_AUTOMATION",
        "EMBEDDED_PAYMENTS",
        "PLATFORM_FEE_COLLECTION",
        "P2P_TRANSFERS",
        "CHARITABLE_DONATIONS",
        "OTHER"
      ],
      "description": "The intended purpose for using the Grid account"
    },
    "SourceOfFundsCategory": {
      "type": "string",
      "enum": [
        "OPERATING_REVENUE",
        "INVESTMENT_INCOME",
        "LOANS",
        "VENTURE_CAPITAL",
        "PERSONAL_SAVINGS",
        "DONATIONS",
        "OTHER"
      ],
      "description": "A structured source-of-funds category for the business"
    }
  }
}