Customer management

Manage your customer information in the Cross River operating system (COS) using either APIs or COS Explorer. This information includes basic details needed to open a bank account or use a credit card, as well as more specific data about the customer, as needed. We call this a customer record.

Before you can open a deposit account or create a debit card you must establish the customer record, sometimes called onboarding.

Customer Onboarding

The customer record is the primary resource containing customer information. Therefore, before creating an account for a customer, you must onboard that customer. The customer record supports classifications of type Personal or Business . Once onboarded, you can associate a customer with one or more accounts.

The example below shows an onboarding request for a personal customer.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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.

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

1
2
3
4
5
POST /core/v1/cm/customers/{businessCustomerId}/beneficial-owners
{
  "ownerCustomerId": "c1210a2d-932e-43ca-be29-f358a4382385",
  "ownerTitle": "President"
}

Customer Name

The Name resource contains all the naming information for both persons and organizations.

1
2
3
4
5
6
PUT /core/v1/cm/customers/{id}/name
{
  "firstName": "Jane",
  "middleName": "Carol",
  "lastName": "Roberts"
}

1
2
3
4
PUT /core/v1/cm/customers/{id}/name
{
  "entityName": "Acme Co"
}

Customer Profile

The Profile resource collects various banking-relevant information for the customer.

1
2
3
4
5
6
7
8
9
10
11
12
13
PUT /core/v1/cm/customers/{id}/profile
{
    "regO": false,
    "citizenshipCountryCode": "US",
    "politicallyExposedPerson": false,
    "enableBackupWithholding": false,
    "backupWithholdingPercent": 0,
    "taxIdType": "Ssn",
    "taxId": "123456789",
    "birthDate": "1965-09-15",
    "riskRating": "Low",
    "privacyOptOut": true
}

1
2
3
4
5
6
7
8
9
10
11
12
13
PUT /core/v1/cm/customers/{id}/profile
{
    "citizenshipCountryCode": "US",    
    "enableBackupWithholding": false,
    "backupWithholdingPercent": 0,    
    "taxIdType": "Ein",
    "taxId": "123456789",
    "dateFormed": "2019-09-10",
    "entityType": "Corporation",
    "riskRating": "Low",
    "ownershipType": "LegalEntity",
    "primaryOwnerCustomerId": "be22a7da-f15c-4678-8524-2b2650f929d9",
}

Address

Physical addresses associated with customer.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
POST /core/v1/cm/customers/{id}/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

Email contact information for customer.

1
2
3
4
5
6
POST /core/v1/cm/customers/{id}/emails
{
  "isPrimary": true,
  "emailType": "Personal",
  "emailAddress": "john.smith@crossriver.com"
}

Phones

Phone contact information for customer.

1
2
3
4
5
6
POST /core/v1/cm/customers/{id}/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.

1
2
3
4
5
6
7
8
9
10
11
12
POST /core/v1/cm/customers/{id}/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",
}

Error codes

See COS system error codes, along with lots of other reference information, on the COS reference codes page.