How to add a beneficial owner resource to a customer record

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.

Note

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.

Note

If you are new to customer management, we recommend you read the customer management overview before starting this tutorial.

The tutorial assumes you have a knowledge of APIs and how they work. For more information on sending API calls, see the API overview page.

The tutorial uses these API endpoints

API	Description
POST /core/v1/cm/customers/{businessCustomerId}/beneficial-owners	Adds a beneficial owner resource to customer details.

Before you begin

Make sure you have:

API credentials
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

Add a beneficial owner resource to an existing 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 CR 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.

a. To add identification information

Call POST /core/v1/cm/customers/{customerId}/beneficial-owners. The attributes below are required. A full list of attributes is found here.

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. Read more about idempotency keys here.

Copy

Sample request for POST /core/v1/cm/customers/{customerId}/beneficial-owners

1
2
3
4
5
6
7
8
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.

Copy

Response sample

1
2
3
4
5
6
7
8
9
10
{
  "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",
}