use BeneficialOwner.yaml within business customer

[wuvictor-95]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ready	Preview, Comment	Mar 25, 2026 4:03am

[wuvictor-95]

• use BeneficialOwner.yaml within business customer #296 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

✱ Stainless preview builds

This PR will update the grid SDKs with the following commit messages.

kotlin

feat(api): restructure BeneficialOwner in customers with personalInfo, roles, kycStatus

openapi

fix(types): replace UltimateBeneficialOwner with BeneficialOwner in BusinessCustomer

python

feat(api): restructure customer beneficial owner with nested personal_info and new fields

typescript

feat(api): restructure beneficial owner type in business customers

✅ grid-openapi studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅

⚠️ grid-python studio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ✅

pip install https://pkg.stainless.com/s/grid-python/2e4fb260ac2120fff042017ed088d7be49d60e75/grid-0.0.1-py3-none-any.whl

✅ grid-kotlin studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

⚠️ grid-typescript studio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ✅

npm install https://pkg.stainless.com/s/grid-typescript/fcd1b1a3645d581a5407ddcb95f14ff10bf5915e/dist.tar.gz

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-03-25 04:19:40 UTC

[greptile-apps]

Greptile Summary

This PR replaces the legacy UltimateBeneficialOwner schema with the richer, more fully-featured BeneficialOwner schema in BusinessCustomer.beneficialOwners, and also adds ownershipPercentage to the list of required fields on BeneficialOwner. The bundled openapi.yaml / mintlify/openapi.yaml files are updated accordingly via make build.

  (‐^▽^‐)  Great clean-up, Victor!
   /|  |\

• Schema consolidation — UltimateBeneficialOwner.yaml is deleted; BusinessCustomer.beneficialOwners[] now references the canonical BeneficialOwner schema, which includes id, customerId, kycStatus, personalInfo, and timestamp fields.
• ownershipPercentage made required — Added to required in BeneficialOwner.yaml. Worth confirming the server always returns this for all roles (including non-UBO roles like DIRECTOR).
• Bundle regenerated correctly — Both openapi.yaml and mintlify/openapi.yaml reflect the source changes and the duplicate schema definitions at the bottom of the file are cleaned up.

Confidence Score: 5/5

• Safe to merge — the change is a clean consolidation of two overlapping schemas with one minor open question about ownershipPercentage requiredness.
• The schema consolidation is clearly intentional and consistent across the source YAML and both bundled outputs. The only concern is whether ownershipPercentage being required is correct for non-ownership roles, but this is a design question rather than a spec error and the fix (value of 0) is trivially valid.
• openapi/components/schemas/customers/BeneficialOwner.yaml — confirm ownershipPercentage required is correct for all possible BeneficialOwnerRole values.

Important Files Changed

Filename	Overview
openapi/components/schemas/customers/BeneficialOwner.yaml	Adds ownershipPercentage to the required array — a potentially breaking change for beneficial owners with non-ownership roles (e.g. DIRECTOR).
openapi/components/schemas/customers/BusinessCustomer.yaml	Replaces the UltimateBeneficialOwner reference with the richer BeneficialOwner schema for the beneficialOwners array — clean, intentional change.
openapi/components/schemas/customers/UltimateBeneficialOwner.yaml	Deleted — superseded by the BeneficialOwner schema, which is more complete and consistent with the rest of the API.
openapi.yaml	Regenerated bundle: moves BeneficialOwner-family schemas earlier in the file (near BusinessCustomer) and removes the duplicate definitions that previously lived at the bottom.
mintlify/openapi.yaml	Mirror of openapi.yaml bundle regeneration — no independent changes.

Class Diagram

%%{init: {'theme': 'neutral'}}%%
classDiagram
    class BusinessCustomer {
        +Customer base
        +BusinessCustomerFields fields
        +BusinessInfo businessInfo
        +BeneficialOwner[] beneficialOwners
    }
    class BeneficialOwner {
        +string id
        +string customerId
        +BeneficialOwnerRole[] roles
        +integer ownershipPercentage
        +BeneficialOwnerPersonalInfo personalInfo
        +KycStatus kycStatus
        +datetime createdAt
        +datetime updatedAt
    }
    class BeneficialOwnerPersonalInfo {
        +string firstName
        +string middleName
        +string lastName
        +date birthDate
        +string nationality
        +string email
        +string phoneNumber
        +Address address
        +IdentificationType idType
        +string identifier
        +string countryOfIssuance
    }
    class UltimateBeneficialOwner {
        <<deleted>>
        +string fullName
        +string emailAddress
        +string phoneNumber
        +string taxId
        +date birthDate
        +string nationality
        +Address address
        +string individualType
        +number percentageOwnership
        +string title
    }
    BusinessCustomer --> BeneficialOwner : beneficialOwners
    BeneficialOwner --> BeneficialOwnerPersonalInfo : personalInfo
    BusinessCustomer ..> UltimateBeneficialOwner : was

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: openapi/components/schemas/customers/BeneficialOwner.yaml
Line: 4

Comment:
**`ownershipPercentage` required for all roles**

Making `ownershipPercentage` required means every `BeneficialOwner` the server returns must include it — including those whose `roles` are purely non-ownership roles like `DIRECTOR`, `COMPANY_OFFICER`, or `CONTROL_PERSON`. A director with no equity stake would need to carry `ownershipPercentage: 0`, which is semantically different from the field simply being absent.

If the server always supplies this value, this is fine. But if some beneficial owners are created/returned without an ownership percentage, removing it from `required` (or keeping it optional with a note that it defaults to `0`) would more accurately reflect the data model.

```suggestion
  - ownershipPercentage
```
Consider removing `ownershipPercentage` from `required` if it may be absent for non-UBO roles, and instead document it as optional with a range of 0–100.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (2): Last reviewed commit: "use BeneficialOwner.yaml within business..." | Re-trigger Greptile}

[greptile-apps]

ownershipPercentage required for all roles

Making ownershipPercentage required means every BeneficialOwner the server returns must include it — including those whose roles are purely non-ownership roles like DIRECTOR, COMPANY_OFFICER, or CONTROL_PERSON. A director with no equity stake would need to carry ownershipPercentage: 0, which is semantically different from the field simply being absent.

If the server always supplies this value, this is fine. But if some beneficial owners are created/returned without an ownership percentage, removing it from required (or keeping it optional with a note that it defaults to 0) would more accurately reflect the data model.

Suggested change

	- customerId
	- ownershipPercentage

Consider removing ownershipPercentage from required if it may be absent for non-UBO roles, and instead document it as optional with a range of 0–100.

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/components/schemas/customers/BeneficialOwner.yaml
Line: 4

Comment:
**`ownershipPercentage` required for all roles**

Making `ownershipPercentage` required means every `BeneficialOwner` the server returns must include it — including those whose `roles` are purely non-ownership roles like `DIRECTOR`, `COMPANY_OFFICER`, or `CONTROL_PERSON`. A director with no equity stake would need to carry `ownershipPercentage: 0`, which is semantically different from the field simply being absent.

If the server always supplies this value, this is fine. But if some beneficial owners are created/returned without an ownership percentage, removing it from `required` (or keeping it optional with a note that it defaults to `0`) would more accurately reflect the data model.

```suggestion
  - ownershipPercentage
```
Consider removing `ownershipPercentage` from `required` if it may be absent for non-UBO roles, and instead document it as optional with a range of 0–100.

How can I resolve this? If you propose a fix, please make it concise.

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}