Add a beneficial owner
What you will learn
✅ How to update a COS customer record with a beneficial owner resource
If you are a Cross River partner using our partner-managed issuing 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.
If you are new to customer management, we recommend you read our customer onboarding documentation.
The tutorial assumes you have a knowledge of APIs and how they work. Refer to API basics for more details.
The tutorial uses this API endpoint:
API | Description |
|---|---|
Adds a beneficial owner resource to customer details. |
What is 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 has 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.
Before you begin
Make sure you have:
- Customer ID of the business customer record to be updated (only available once the business is onboarded).
- Customer ID of the beneficial owner personal customer record (only available once the beneficial owner is onboarded) 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
Add beneficial owner resource to record
When you onboard a business customer, you'll need to add any beneficial owners as resources for the business. Add the beneficial owner to the existing customer record.
If you're using {{BIN}} 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 an existing business customer record.
To add identification information
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.
curl -X POST
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: Bearer <token>'
-d '{ \
"ownerCustomerId": "83454c7a-e5d3-4f3a-8633-11dd49389de2",
"ownerTitle": "CEO",
}' 'https://sandbox.crbcos.com/Core/v1/cm/customers/e2a76a89-b5ff-46f1-bf4d-494579d7bb71/beneficial-owners'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.
{
"id": "6d441e6d-cd94-4be1-bd30-3890fcad3100",
"customerId": "e2a76a89-b5ff-46f1-bf4d-494579d7bb71",
"ownerCustomerId": "83454c7a-e5d3-4f3a-8633-11dd49389de2",
"status": "Active",
"ownerTitle": "CEO",
"partnerId": "0497b3ba-ab2f-4537-8257-4af39d7a5cf7",
"createdAt": "2024-01-07T08:13:08.464Z",
"lastModifiedAt": "2024-01-07T08:13:08.464Z",
}