Add a beneficial owner
A beneficial owner is a person who owns 25% or more of a business. For regulatory reasons, you need to create a Beneficial Owner resource in a Business customer record for each beneficial owner of that business. Each beneficial owner will have a personal customer record that includes a unique customer ID. The ownerCustomerId attribute in the call described here references the Personal customer ID for each beneficial owner. You usually add beneficial owner resources to the business customer record immediately after onboarding a business.
If you are a CR partner using CR Credit BIN sponsorship to provide commercial card services (and not to individual cardholders) use this endpoint to associate individual cardholder customer records with their employer business customer record.
In this tutorial, you'll learn how to:
✅ Update a COS customer record with a beneficial owner resource.
If you are new to customer management, we recommend you read our Customer Management documentation.
The tutorial assumes you have a knowledge of APIs and how they work. Refer to the API overview page for more details.
The tutorial uses these API endpoints
API | Description |
|---|---|
POST /core/v1/cm/customers/{businessCustomerId}/beneficial-owners | Adds a beneficial owner resource to customer details. |
Make sure you have:
- Customer ID of the business customer record to be updated (only available once the business is added to COS)
- Customer ID of the beneficial owner personal customer record (only available once the beneficial owner is added to COS) or the customer ID of the business customer record to associate an individual cardholder customer record with their employer customer record.
- Beneficial owner title as it appears in their customer record
When you onboard a business customer, you'll need to add any beneficial owners as resources for the business.
If you're using Credit BIN sponsorship to provide credit card services for businesses, you need to add each cardholder as a beneficial owner resource to the business customer record. In that case, the ownerTitle for each cardholder is Auth User.
In this tutorial, you'll add the CEO of a business as a beneficial owner resource to a business customer record.
Call POST /core/v1/cm/customers/{customerId}/beneficial-owners. The attributes below are required.
Detail | Request attribute name | Value used in the sample request (not valid) |
|---|---|---|
CR customer ID for the business customer record being updated (provided when the customer was onboarded to COS) | customerId | e2a76a89-b5ff-46f1-bf4d-494579d7bb71 |
Beneficial owner CR customer ID (provided when the beneficial owner was onboarded to COS) | ownerCustomerId | 83454c7a-e5d3-4f3a-8633-11dd49389de2 |
Title or role of the beneficial owner | ownerTitle | CEO |
IMPORTANT We highly recommend you include an idempotency key in your request header to provide duplicate protection in the event of a failure.
A successful API call returns a JSON response confirming the beneficial owner added in COS. The id attribute indicates the COS ID of the beneficial owner record. In the sample below, the ID is 6d441e6d-cd94-4be1-bd30-3890fcad3100. Yours will be different.
