---
title: "Update a beneficial owner"
method: PATCH
path: "/beneficial-owners/{beneficialOwnerId}"
tags: ["KYC/KYB Verifications"]
---

# Update a beneficial owner

`PATCH /beneficial-owners/{beneficialOwnerId}`

Update details of a specific beneficial owner. Only provided fields are updated.

## Path parameters

- `beneficialOwnerId` string, required

## Request body

- BeneficialOwnerUpdateRequest
  - `roles` BeneficialOwnerRole[] — Roles of this person within the business
  - `ownershipPercentage` integer — Percentage of ownership in the business (0-100)
  - `personalInfo` BeneficialOwnerPersonalInfoUpdate — Partial update for beneficial owner personal information. Only provided fields are updated.
    - `firstName` string — First name of the individual
    - `middleName` string — Middle name of the individual
    - `lastName` string — Last name of the individual
    - `birthDate` string, date — Date of birth in ISO 8601 format (YYYY-MM-DD)
    - `nationality` string — Country of nationality (ISO 3166-1 alpha-2)
    - `email` string, email — Email address of the individual
    - `phoneNumber` string — Phone number in E.164 format
    - `address` Address
      - `line1` string, required — Street address line 1
      - `line2` string — Street address line 2
      - `city` string — City
      - `state` string — State/Province/Region
      - `postalCode` string, required — Postal/ZIP code
      - `country` string, required — Country code (ISO 3166-1 alpha-2)
    - `idType` 'SSN' | 'ITIN' | 'EIN' | 'NON_US_TAX_ID' — Type of tax identification
    - `identifier` string — The identification number or value
    - `countryOfIssuance` string — Country that issued the identification (ISO 3166-1 alpha-2)

## Response `200`

Beneficial owner updated successfully

- BeneficialOwner
  - `id` string, required — Unique identifier for this beneficial owner
  - `customerId` string, required — The ID of the business customer this beneficial owner is associated with
  - `roles` BeneficialOwnerRole[], required — Roles of this person within the business
  - `ownershipPercentage` integer, required — Percentage of ownership in the business (0-100)
  - `personalInfo` BeneficialOwnerPersonalInfo, required
    - `firstName` string, required — First name of the individual
    - `middleName` string — Middle name of the individual
    - `lastName` string, required — Last name of the individual
    - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
    - `nationality` string, required — Country of nationality (ISO 3166-1 alpha-2)
    - `email` string, email — Email address of the individual
    - `phoneNumber` string — Phone number in E.164 format
    - `address` Address, required
      - `line1` string, required — Street address line 1
      - `line2` string — Street address line 2
      - `city` string — City
      - `state` string — State/Province/Region
      - `postalCode` string, required — Postal/ZIP code
      - `country` string, required — Country code (ISO 3166-1 alpha-2)
    - `idType` 'SSN' | 'ITIN' | 'EIN' | 'NON_US_TAX_ID', required — Type of tax identification
    - `identifier` string, required — The identification number or value
    - `countryOfIssuance` string — Country that issued the identification (ISO 3166-1 alpha-2)
  - `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.
  - `createdAt` string, date-time, required — When this beneficial owner was created
  - `updatedAt` string, date-time — When this beneficial owner was last updated

## Other responses

- `400` — Bad request - Invalid parameters
- `401` — Unauthorized
- `404` — Beneficial owner not found
- `500` — Internal service error

## Changes

- **2026-08-14** `aaa1fb8782c8` — 1 warning
  - added the new `EXTERNAL_ACCOUNT_VERIFICATION_REQUIRED` enum value to the `code` response property for the response status `400`
- **2026-08-13** `df12ec487f0e` — 1 warning
  - added the new `TRANSACTION_SIZE_LIMIT_EXCEEDED` enum value to the `code` response property for the response status `400`
- **2026-08-11** `b06902b6595a` — 1 warning
  - added the new `CARDHOLDER_KYC_NOT_APPROVED` enum value to the `code` response property for the response status `400`
- **2026-08-06** `526036c12609` — 1 warning
  - added the new `END_USER_TERMS_VERSION_NOT_FOUND` enum value to the `code` response property for the response status `400`
- **2026-07-31** `b21ed434ee6e` — 1 info
  - added the optional property `details/errors` to the response with the `400` status

[Change history](https://skmtc.dev/stainless-api/apis/grid-api/changes/beneficial-owners/:beneficialOwnerId/patch.md)

---

[API](https://skmtc.dev/stainless-api/apis/grid-api.md) · [All operations](https://skmtc.dev/stainless-api/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stainless-api/grid-api/revisions/f0fa3ab7c7b0/schema)