---
title: Add a beneficial owner
slug: tutorials/api/customer-management/add-a-beneficial-owner
description: Demonstrates adding ownership info via POST /core/v1/cm/customers/{customerid}/beneficial-owners.
docTags: 
createdAt: 2024-08-12T13:22:00.077Z
---

## What you will learn

✅ How to update a COS customer record with a beneficial owner resource

:::hint{type="info"}
If you are a Cross River partner using our [partner-managed issuing](docId\:n-sV1g5OiDbnWae2xWnSj) 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.
:::

:::hint{type="info"}
If you are new to customer management, we recommend you read our [customer onboarding](docId\:Nt23Lv6UL3hwB2r5bz4K9) documentation.

The tutorial assumes you have a knowledge of APIs and how they work. Refer to [API basics](docId\:pUTTCwQ5SKLzxYzIn5D1b) for more details.
:::

The tutorial uses this API endpoint:

| API                                                                                             | Description                                           |
| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [POST /core/v1/cm/customers/{customerId}/beneficial-owners](docId\:EOH9pzYARQnyhe9mh979u)  | 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:

- [API credentials](docId\:wmg-1Fqwq3bj-D3c3HFfs) 
- Customer ID of the business customer record to be updated (only available once the business is [onboarded](docId\:iXWQHkcTI4dw4d_LoutGh)).
- Customer ID of the beneficial owner personal customer record (only available once the beneficial owner is [onboarded](docId\:iXWQHkcTI4dw4d_LoutGh)) 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

:::::WorkflowBlock
::::WorkflowBlockItem
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**                                      |

:::hint{type="warning"}
**IMPORTANT**
We highly recommend you include an [idempotency key](docId\:xQC2lRsG0xVv_9NMkqxKk) in your request header to provide duplicate protection in the event of a failure.
:::

```curl
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'
```
::::

:::WorkflowBlockItem
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.
:::

::::WorkflowBlockItem
:::CodeblockTabs
Response sample

```json
{
  "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",
}
```
:::
::::

:::WorkflowBlockItem

:::
:::::