Skip to main content
POST
/
beneficial-owners
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": "jane.smith@acmecorp.com",
    "phoneNumber": "+14155550192",
    "countryOfIssuance": "US"
  }
}
'
{
  "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"
}

Documentation Index

Fetch the complete documentation index at: https://ramps-05-22-docs-annotate-cards-intro-snippet-triggers-mint.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

Response

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
​
kycStatus
enum<string>
required

The current KYC status of a customer

Available options:
UNVERIFIED,
PENDING,
APPROVED,
REJECTED
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"