Create a beneficial owner

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": "jane.smith@acmecorp.com",
    "phoneNumber": "+14155550192",
    "countryOfIssuance": "US"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
    }
  })
};

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 mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"customerId\": \"Customer:019542f5-b3e7-1d02-0000-000000000001\",\n  \"roles\": [\n    \"UBO\",\n    \"DIRECTOR\"\n  ],\n  \"ownershipPercentage\": 51,\n  \"personalInfo\": {\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Smith\",\n    \"birthDate\": \"1978-06-15\",\n    \"nationality\": \"US\",\n    \"address\": {\n      \"line1\": \"123 Main Street\",\n      \"postalCode\": \"94105\",\n      \"country\": \"US\",\n      \"line2\": \"Apt 4B\",\n      \"city\": \"San Francisco\",\n      \"state\": \"CA\"\n    },\n    \"idType\": \"SSN\",\n    \"identifier\": \"123-45-6789\",\n    \"middleName\": \"Marie\",\n    \"email\": \"jane.smith@acmecorp.com\",\n    \"phoneNumber\": \"+14155550192\",\n    \"countryOfIssuance\": \"US\"\n  }\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/beneficial-owners")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

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

{
  "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"
}

{
  "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": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

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

POST

beneficial-owners

Create a beneficial owner

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": "jane.smith@acmecorp.com",
    "phoneNumber": "+14155550192",
    "countryOfIssuance": "US"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
    }
  })
};

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 mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"customerId\": \"Customer:019542f5-b3e7-1d02-0000-000000000001\",\n  \"roles\": [\n    \"UBO\",\n    \"DIRECTOR\"\n  ],\n  \"ownershipPercentage\": 51,\n  \"personalInfo\": {\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Smith\",\n    \"birthDate\": \"1978-06-15\",\n    \"nationality\": \"US\",\n    \"address\": {\n      \"line1\": \"123 Main Street\",\n      \"postalCode\": \"94105\",\n      \"country\": \"US\",\n      \"line2\": \"Apt 4B\",\n      \"city\": \"San Francisco\",\n      \"state\": \"CA\"\n    },\n    \"idType\": \"SSN\",\n    \"identifier\": \"123-45-6789\",\n    \"middleName\": \"Marie\",\n    \"email\": \"jane.smith@acmecorp.com\",\n    \"phoneNumber\": \"+14155550192\",\n    \"countryOfIssuance\": \"US\"\n  }\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/beneficial-owners")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

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

{
  "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"
}

{
  "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": "TRANSACTION_NOT_FOUND",
  "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>

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

Minimum array length: 1

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

Beneficial owner created successfully

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"

Using the API

API documentation

Create a beneficial owner

Authorizations

Body

Response