Create a beneficial owner

Add a beneficial owner, director, or company officer to a business customer. The beneficial owner will go through KYC verification automatically.

POST /beneficial-owners

cURL

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/beneficial-owners \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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": "[e-mail]",
    "phoneNumber": "[phone]",
    "countryOfIssuance": "US"
  }
}
'

import LightsparkGrid from '@lightsparkdev/grid';

const client = new LightsparkGrid({
  username: process.env['GRID_CLIENT_ID'], // This is the default and can be omitted
  password: process.env['GRID_CLIENT_SECRET'], // This is the default and can be omitted
});

const beneficialOwner = await client.beneficialOwners.create({
  customerId: 'Customer:019542f5-b3e7-1d02-0000-000000000001',
  ownershipPercentage: 51,
  personalInfo: {
    address: {
      country: 'US',
      line1: '123 Main Street',
      postalCode: '94105',
    },
    birthDate: '1978-06-15',
    firstName: 'Jane',
    identifier: '123-45-6789',
    idType: 'SSN',
    lastName: 'Smith',
    nationality: 'US',
  },
  roles: ['UBO', 'DIRECTOR'],
});

console.log(beneficialOwner.id);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.BeneficialOwner
import com.lightspark.grid.models.beneficialowners.BeneficialOwnerCreateRequest
import com.lightspark.grid.models.beneficialowners.BeneficialOwnerPersonalInfo
import com.lightspark.grid.models.customers.externalaccounts.Address
import java.time.LocalDate

fun main() {
    val client: LightsparkGridClient = LightsparkGridOkHttpClient.fromEnv()

    val params: BeneficialOwnerCreateRequest = BeneficialOwnerCreateRequest.builder()
        .customerId("Customer:019542f5-b3e7-1d02-0000-000000000001")
        .ownershipPercentage(51L)
        .personalInfo(BeneficialOwnerPersonalInfo.builder()
            .address(Address.builder()
                .country("US")
                .line1("123 Main Street")
                .postalCode("94105")
                .build())
            .birthDate(LocalDate.parse("1978-06-15"))
            .firstName("Jane")
            .identifier("123-45-6789")
            .idType(BeneficialOwnerPersonalInfo.IdType.SSN)
            .lastName("Smith")
            .nationality("US")
            .build())
        .addRole(BeneficialOwnerCreateRequest.Role.UBO)
        .addRole(BeneficialOwnerCreateRequest.Role.DIRECTOR)
        .build()
    val beneficialOwner: BeneficialOwner = client.beneficialOwners().create(params)
}

201

{
  "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": "[e-mail]",
    "phoneNumber": "[phone]",
    "countryOfIssuance": "US"
  },
  "kycStatus": "APPROVED",
  "createdAt": "2025-10-03T12:00:00Z",
  "updatedAt": "2025-10-03T12:00:00Z"
}

{
  "status": 400,
  "message": "<string>",
  "details": {}
}

{
  "status": 401,
  "message": "<string>",
  "details": {}
}

{
  "status": 404,
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "message": "<string>",
  "details": {}
}

Authorizations

Authorization · string · header · required

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

Body

application/json

customerId · string · required

The ID of the business customer this beneficial owner is associated with

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000001"

roles · enum<string>[] · required

Roles of this person within the business

Role of the beneficial owner within the business

Available options: UBO, DIRECTOR, COMPANY_OFFICER, CONTROL_PERSON, TRUSTEE, GENERAL_PARTNER

Example:

["UBO", "DIRECTOR"]

ownershipPercentage · integer · required

Percentage of ownership in the business (0-100). Relevant when role includes UBO.

Required range: 0 <= x <= 100

Example:

51

personalInfo · object · required

Show child attributes

Response

201

application/json

Beneficial owner created successfully

id · string · required

Unique identifier for this beneficial owner

Example:

"BeneficialOwner:019542f5-b3e7-1d02-0000-000000000001"

customerId · string · required

The ID of the business customer this beneficial owner is associated with

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000001"

roles · enum<string>[] · required

Roles of this person within the business

Role of the beneficial owner within the business

Available options: UBO, DIRECTOR, COMPANY_OFFICER, CONTROL_PERSON, TRUSTEE, GENERAL_PARTNER

Example:

["UBO", "DIRECTOR"]

ownershipPercentage · integer · required

Percentage of ownership in the business (0-100)

Required range: 0 <= x <= 100

Example:

51

personalInfo · object · required

Show child attributes

kycStatus · enum<string> · required

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.

Available options: UNVERIFIED, PENDING, APPROVED, REJECTED, HOLD

Example:

"APPROVED"

createdAt · string<date-time> · required

When this beneficial owner was created

Example:

"2025-10-03T12:00:00Z"

updatedAt · string<date-time>

When this beneficial owner was last updated

Example:

"2025-10-03T12:00:00Z"