Update a beneficial owner

curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/beneficial-owners/{beneficialOwnerId} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "roles": [
    "UBO",
    "DIRECTOR"
  ],
  "ownershipPercentage": 51,
  "personalInfo": {
    "firstName": "Jane",
    "middleName": "Marie",
    "lastName": "Smith",
    "birthDate": "1978-06-15",
    "nationality": "US",
    "email": "jane.smith@acmecorp.com",
    "phoneNumber": "+14155550192",
    "idType": "SSN",
    "identifier": "123-45-6789",
    "countryOfIssuance": "US"
  }
}
'

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    roles: ['UBO', 'DIRECTOR'],
    ownershipPercentage: 51,
    personalInfo: {
      firstName: 'Jane',
      middleName: 'Marie',
      lastName: 'Smith',
      birthDate: '1978-06-15',
      nationality: 'US',
      email: 'jane.smith@acmecorp.com',
      phoneNumber: '+14155550192',
      idType: 'SSN',
      identifier: '123-45-6789',
      countryOfIssuance: 'US'
    }
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/beneficial-owners/{beneficialOwnerId}', 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  \"roles\": [\n    \"UBO\",\n    \"DIRECTOR\"\n  ],\n  \"ownershipPercentage\": 51,\n  \"personalInfo\": {\n    \"firstName\": \"Jane\",\n    \"middleName\": \"Marie\",\n    \"lastName\": \"Smith\",\n    \"birthDate\": \"1978-06-15\",\n    \"nationality\": \"US\",\n    \"email\": \"jane.smith@acmecorp.com\",\n    \"phoneNumber\": \"+14155550192\",\n    \"idType\": \"SSN\",\n    \"identifier\": \"123-45-6789\",\n    \"countryOfIssuance\": \"US\"\n  }\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/beneficial-owners/{beneficialOwnerId}")
  .patch(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": {}
}

PATCH

beneficial-owners

{beneficialOwnerId}

Update a beneficial owner

curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/beneficial-owners/{beneficialOwnerId} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "roles": [
    "UBO",
    "DIRECTOR"
  ],
  "ownershipPercentage": 51,
  "personalInfo": {
    "firstName": "Jane",
    "middleName": "Marie",
    "lastName": "Smith",
    "birthDate": "1978-06-15",
    "nationality": "US",
    "email": "jane.smith@acmecorp.com",
    "phoneNumber": "+14155550192",
    "idType": "SSN",
    "identifier": "123-45-6789",
    "countryOfIssuance": "US"
  }
}
'

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    roles: ['UBO', 'DIRECTOR'],
    ownershipPercentage: 51,
    personalInfo: {
      firstName: 'Jane',
      middleName: 'Marie',
      lastName: 'Smith',
      birthDate: '1978-06-15',
      nationality: 'US',
      email: 'jane.smith@acmecorp.com',
      phoneNumber: '+14155550192',
      idType: 'SSN',
      identifier: '123-45-6789',
      countryOfIssuance: 'US'
    }
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/beneficial-owners/{beneficialOwnerId}', 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  \"roles\": [\n    \"UBO\",\n    \"DIRECTOR\"\n  ],\n  \"ownershipPercentage\": 51,\n  \"personalInfo\": {\n    \"firstName\": \"Jane\",\n    \"middleName\": \"Marie\",\n    \"lastName\": \"Smith\",\n    \"birthDate\": \"1978-06-15\",\n    \"nationality\": \"US\",\n    \"email\": \"jane.smith@acmecorp.com\",\n    \"phoneNumber\": \"+14155550192\",\n    \"idType\": \"SSN\",\n    \"identifier\": \"123-45-6789\",\n    \"countryOfIssuance\": \"US\"\n  }\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/beneficial-owners/{beneficialOwnerId}")
  .patch(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>

Path Parameters

beneficialOwnerId

string

required

Beneficial owner ID

Body

application/json

roles

enum<string>[]

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

Percentage of ownership in the business (0-100)

Required range: 0 <= x <= 100

Example:

51

personalInfo

object

Partial update for beneficial owner personal information. Only provided fields are updated.

Show child attributes

Response

Beneficial owner updated 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

Update a beneficial owner

Authorizations

Path Parameters

Body

Response