Sign in

v5

OpenAPI 3.1.0Proprietary2026-08-011476181.4 MB
KYC/KYB Verifications

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

Request body

customerIdstring required

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

rolesBeneficialOwnerRole[] required

Roles of this person within the business

ownershipPercentageinteger required

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

Example request

{
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "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",
    "address": {
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "country": "US"
    },
    "idType": "SSN",
    "identifier": "123-45-6789",
    "countryOfIssuance": "US"
  }
}

Response

Beneficial owner created successfully

idstring required

Unique identifier for this beneficial owner

customerIdstring required

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

rolesBeneficialOwnerRole[] required

Roles of this person within the business

ownershipPercentageinteger required

Percentage of ownership in the business (0-100)

kycStatus'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' | 'HOLD' 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.

createdAtstring date-time required

When this beneficial owner was created

updatedAtstring date-time

When this beneficial owner was last updated

Example response

{
  "id": "BeneficialOwner:019542f5-b3e7-1d02-0000-000000000001",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "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",
    "address": {
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "country": "US"
    },
    "idType": "SSN",
    "identifier": "123-45-6789",
    "countryOfIssuance": "US"
  },
  "kycStatus": "APPROVED",
  "createdAt": "2025-10-03T12:00:00Z",
  "updatedAt": "2025-10-03T12:00:00Z"
}