---
title: Customer record
slug: ops-and-admin/customer-record
description: Create and manage customer records for Cross River services, ensuring compliance with KYC/KYB regulations through effective onboarding and API integration.
docTags: 
createdAt: 2025-04-21T08:23:12.914Z
---

## What is a customer record

Most of the time, if you want to offer a feature or service your customers through Cross River, you must first create a *customer record*, sometimes called *onboarding *the customer. A customer record is just that, a record of details of an individual or business. This record includes customer communication details, tax information and other data. The customer record is a primary source of information for creating a bank account, for example. You can associate a customer with more than one bank account.

Cross River also uses the customer record for the Know Your Customer (KYC) and Know your Business (KYB) activities. 

Create/onboard a customer either [by API](docId\:Q4-jm-3VHwwmDDeEzxEWg) or using [COS Explorer](docId\:FfHFeajqLBBvqME-M5lwl).

:::hint{type="warning"}
**IMPORTANT**
Some customer endpoints include a `dueDiligence` resource that may or may not be required when onboarding customers. Your assigned compliance liaison communicates requirements for any Due Diligence fields during your onboarding process. Due diligence fields also appear when you create a customer using COS Explorer.
:::

## API Examples

The example below shows how to [onboard a customer ](docId\:isgkj7NIS9jHmyu3UPUBk)for a personal customer. 

:::CodeblockTabs
Onboard Person Request

```curl
POST /core/v1/cm/customers
{
  "partnerId": "7cc038be-fde9-4455-b27b-1497cf667362",
  "name": {
    "prefix": "Mr.",
    "firstName": "John",
    "middleName": "Robert",
    "lastName": "Smith",
    "suffix": "Jr.",
    "preferredName": "Jim"
  },
  "classification": "Personal",
  "profile": {
    "regO": false,
    "citizenshipCountryCode": "US",
    "politicallyExposedPerson": false,
    "enableBackupWithholding": false,
    "backupWithholdingPercent": 0,
    "taxIdType": "Ssn",
    "taxId": "123456789",
    "birthDate": "1965-09-15",
    "riskRating": "Low",
    "privacyOptOut": true
  }
}
```
:::

Onboard a business customer such as corporation or LLC using the same endpoint with slightly different attributes.

```curl
POST /core/v1/cm/customers
{
  "partnerId": "a24cba49-2bb6-431d-a867-1de81d6e4127",
  "name": {
    "entityName": "ACME CO",
  },
  "classification": "Business",
  "profile": {
    "citizenshipCountryCode": "US",    
    "enableBackupWithholding": false,
    "backupWithholdingPercent": 0,    
    "taxIdType": "Ein",
    "taxId": "123456789",
    "dateFormed": "2019-09-10",
    "entityType": "Corporation",
    "riskRating": "Low",
    "ownershipType": "LegalEntity",
    "primaryOwnerCustomerId": "f9321f7f-3712-46e1-b965-2b79ead64dc9",
  }
}
```

Regardless of whether you are onboarding a personal or business customer, the `primaryOwnerCustomerId` attribute must contain a customer ID referencing a customer record of type Personal. So to onboard a business, you must first create a personal customer record for the primary owner of that business.

:::hint{type="info"}
Every customer has an identifying ID in the system in GUIDformat.

In COS Explorer find this ID at the end in the URL of the customer details page:
../explorer2/core/cm/customers/details/**c3f1d6e8-3bca-48e5-9249-b30400b3ab47**

When you create a customer using the API, this ID is returned in the response.

Use this ID to find the customer in COS Explorer, or to run API calls about this customer.
:::

### Beneficial owners

A beneficial owner is a person who owns 25% or more of a business. For regulatory reasons, you need to [create a beneficial owner ](docId\:EOH9pzYARQnyhe9mh979u)  resource in a *Business* customer record for each beneficial owner of that business. The `ownerCustomerId` attribute references the Personal customer record for each beneficial owner. You usually add beneficial owner resources to the business customer record immediately after onboarding a business.

```curl
POST /core/v1/cm/customers/{customerId}/beneficial-owners
{
  "ownerCustomerId": "c1210a2d-932e-43ca-be29-f358a4382385",
  "ownerTitle": "President"
}
```

### Address

The physical addresses associated with customer can be [updated](docId\:tWpyIp5zxe-kjEJqEUqfc).

```curl
POST /core/v1/cm/customers/{customerId}/addresses
{
  "isPrimary": true,
  "status": "Active",
  "classification": "Residential",
  "addressType": "Home",
  "street1": "123 Maple Street",
  "street2": "Apt. 12",
  "street3": "",
  "city": "New York",
  "state": "NY",
  "postalCode": "10025",
  "countryCode": "US",
}
```

### Email addresses

[Update email](docId\:ghuoBTAsQ0vfLcEaWXPte) contact information for customer.

```curl
POST /core/v1/cm/customers/{customerId}/emails
{
  "isPrimary": true,
  "emailType": "Personal",
  "emailAddress": "john.smith@crossriver.com"
}
```

### Phones

[Update phone](docId:5bNWSnxsqTB_GtuntlnPW) contact information for customer.

```curl
POST /core/v1/cm/customers/{customerId}/phones
{
  "phoneType": "Home",
  "isPrimary": true,
  "phoneNumber": "2015551234"
}
```

### Identifications

Identifications are used to track metadata for customer-identifying documents such as driver's licenses and passports. [Add ID details](docId\:QjfGSujVfqoxCpJiqzLfF) can be used to add new ID details.

```curl
POST /core/v1/cm/customers/{customerId}/identifications
{
  "isPrimary": true,
  "idNumber": "DL123456789",
  "idType": "DriversLicense",
  "issuedDate": "2018-08-30",
  "expDate": "2018-08-30",
  "verifiedDate": "2018-08-30",
  "issuingAuthority": "NJ DMV",
  "issuingStateOrProvince": "NJ",
  "issuingCountryCode": "US",
}
```

#