List beneficial owners

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/beneficial-owners \
  --header 'Authorization: Basic <encoded-value>'

const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://api.lightspark.com/grid/2025-10-13/beneficial-owners', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/beneficial-owners")
  .get()
  .addHeader("Authorization", "Basic <encoded-value>")
  .build()

val response = client.newCall(request).execute()

{
  "data": [
    {
      "id": "BeneficialOwner:019542f5-b3e7-1d02-0000-000000000001",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "roles": [
        "UBO",
        "DIRECTOR"
      ],
      "ownershipPercentage": 51,
      "personalInfo": {
        "firstName": "Jane",
        "lastName": "Smith",
        "birthDate": "1978-06-15",
        "nationality": "US",
        "address": {
          "line1": "123 Main Street",
          "postalCode": "94105",
          "country": "US",
          "line2": "Apt 4B",
          "city": "San Francisco",
          "state": "CA"
        },
        "idType": "SSN",
        "identifier": "123-45-6789",
        "middleName": "Marie",
        "email": "jane.smith@acmecorp.com",
        "phoneNumber": "+14155550192",
        "countryOfIssuance": "US"
      },
      "kycStatus": "APPROVED",
      "createdAt": "2025-10-03T12:00:00Z",
      "updatedAt": "2025-10-03T12:00:00Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "<string>",
  "totalCount": 123
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

GET

beneficial-owners

List beneficial owners

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/beneficial-owners \
  --header 'Authorization: Basic <encoded-value>'

const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://api.lightspark.com/grid/2025-10-13/beneficial-owners', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/beneficial-owners")
  .get()
  .addHeader("Authorization", "Basic <encoded-value>")
  .build()

val response = client.newCall(request).execute()

{
  "data": [
    {
      "id": "BeneficialOwner:019542f5-b3e7-1d02-0000-000000000001",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "roles": [
        "UBO",
        "DIRECTOR"
      ],
      "ownershipPercentage": 51,
      "personalInfo": {
        "firstName": "Jane",
        "lastName": "Smith",
        "birthDate": "1978-06-15",
        "nationality": "US",
        "address": {
          "line1": "123 Main Street",
          "postalCode": "94105",
          "country": "US",
          "line2": "Apt 4B",
          "city": "San Francisco",
          "state": "CA"
        },
        "idType": "SSN",
        "identifier": "123-45-6789",
        "middleName": "Marie",
        "email": "jane.smith@acmecorp.com",
        "phoneNumber": "+14155550192",
        "countryOfIssuance": "US"
      },
      "kycStatus": "APPROVED",
      "createdAt": "2025-10-03T12:00:00Z",
      "updatedAt": "2025-10-03T12:00:00Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "<string>",
  "totalCount": 123
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

API token authentication using format <api token id>:<api client secret>

Query Parameters

customerId

string

required

The business customer ID

limit

integer

default:20

Maximum number of results to return (default 20, max 100)

Required range: 1 <= x <= 100

cursor

string

Cursor for pagination (returned from previous request)

Response

Successful operation

data

object[]

required

List of beneficial owners matching the filter criteria

Show child attributes

hasMore

boolean

required

Indicates if more results are available beyond this page

nextCursor

string

Cursor to retrieve the next page of results (only present if hasMore is true)

totalCount

integer

Total number of results matching the criteria

Using the API

API documentation

List beneficial owners

Authorizations

Query Parameters

Response