How to onboard a customer

Before you use banking services offered at Cross River, you need to create a customer record for each of your customers. The customer onboarding process includes creating a customer record and adding relevant customer information.

All customers are automatically scanned for regulatory compliance purposes, so you need to register for relevant webhooks events to receive customer record status updates.

In this tutorial, you'll learn how to

Create a new customer

Add relevant customer details, including customer address and phone number

Retrieve information about a customer

Note

If you are new to customer management, we recommend you read our customer management documentation.

The tutorial assumes you have a knowledge of APIs and how they work. Refer to the API overview page for more details.

The tutorial uses these API endpoints.

API	Description
POST /core/v1/cm/customers	Create a new customer record
GET core/v1/cm/customers/{id}	Retrieve customer information
POST /core/v1/cm/customers/{customerId}/addresses	Add or edit the customer address
POST /core/v1/cm/customers/{customerId}/phones	Add or edit the customer phone number

The tutorial uses these webhooks.

Webhook	Description
`Core.Customer.Onboarded`	Notifies you that the customer record has been created
`Core.Customer.Ofac.Changed`	Notifies you that a customer's OFAC status has been updated
`Core.Customer.PepScan.Changed`	Notifies you that a customer's PEP status has been updated

Before you begin

Make sure you have:

API credentials
Partner ID

1. Register the relevant webhook events

To receive the webhook events for this tutorial you need to register each specific webhook event type. Once you are registered, the event objects are sent to the registered URLs.

The event object contains a list of resource identifiers used to download details on each event.

After the request to onboard a customer is submitted, you need to stay informed of the result of the compliance scan and that the customer record is created.

2. Register the customer

The customer record contains customer information. The customer record supports both classifications of types Personal or Business. Once registered, a customer can be associated with one or more accounts.

In this tutorial, we'll onboard Peter Griffin. First, let's create a customer record. We are registering Peter as a Personal customer.

Note
To onboard a business customer, first create a personal customer record for the primary owner of that business.

a. To create the customer record

Call POST /core/v1/cm/customers. For this call these attributes are required.

`partnerId`	Your unique partner ID
`classification`	The customer classification. Either: Personal Business
`name`	The object containing the customer name details
`profile`	The customer banking profile. This includes: reg0 Politically exposed person (PEP) Customer risk level Tax ID and Tax ID type

A full list of attributes is found here.

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

Create a customer record

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
POST /core/v1/cm/customers
{
  "partnerId": "6e80b097-693c-4592-8440-02f345335bbf",
  "name": {
    "firstName": "Peter",
    "lastName": "Griffin"
  },
  "classification": "Personal",
  "profile": {
    "regO": false,
    "politicallyExposedPerson": false,
    "taxIdType": "Ssn",
    "taxId": "119988776",
    "birthDate": "1953-09-22",
    "riskRating": "Low"
  }
}

The customer record is created.

The unique customer ID is the first line of the response body.

Copy

Onboarding a customer response body

{
  "id": "9052b6a5-3f09-41d1-b526-ade80104eb79",
  "cifNumber": "32653745014",
  "classification": "Personal",
  "status": "Active",
  "ofac": "Pending",
  "pepScan": "Pending",
  "name": {
    "firstName": "Peter",
    "lastName": "Griffin",
    "fullName": "Peter Griffin"
  },
  "profile": {
    "regO": false,
    "politicallyExposedPerson": false,
    "enableBackupWithholding": false,
    "taxIdType": "Ssn",
    "taxId": "119988776",
    "birthDate": "1953-09-22",
    "riskRating": "Low"
  },
  "createdAt": "2021-01-25T17:55:24.4422582-05:00",
  "lastModifiedAt": "2021-01-25T17:55:24.4432543-05:00",
  "partnerId": "6e80b097-693c-4592-8440-02f345335bbf"
}

The Core.Customer.Onboarded webhook event is triggered when the customer record is created.

Copy

Customer onboarded event

{
  "id": "3d9c5e1a-623b-4cf2-812e-ade80105048e",
  "eventName": "Core.Customer.Onboarded",
  "status": "Pending",
  "partnerId": "30dee145-b6a2-4058-8dc3-ac4000dee91f",
  "createdAt": "2021-11-22T10:50:20.553-05:00",
  "resources": [
    "core/v1/cm/customers/9052b6a5-3f09-41d1-b526-ade80104eb79"
  ],
  "details": []
}

CR scans a new customer record for OFAC and PEP compliance.

Note

Sometimes the results of the scan require a review by the our Anti-Money Laundering (AML) team.

On scan completion, Core.Customer.Ofac.Changed and Core.Customer.PepScan.Changed webhook events return with a status. Customers with no compliance issues show a Clear status.

Copy

Customer OFAC scan changed

1
2
3
4
5
6
7
8
9
10
11
{
  "id": "45db5592-56ee-41f5-85e7-ade8010571ce",
  "eventName": "Core.Customer.Ofac.Changed",
  "status": "Pending",
  "partnerId": "30dee145-b6a2-4058-8dc3-ac4000dee91f",
  "createdAt": "2021-11-22T10:51:53.657-05:00",
  "resources": [
    "core/v1/cm/customers/9052b6a5-3f09-41d1-b526-ade80104eb79"
  ],
  "details": []
}

Copy

Customer PEP scan changed

1
2
3
4
5
6
7
8
9
10
11
{
  "id": "a5000831-3e01-4231-9ec2-ade8010571c5",
  "eventName": "Core.Customer.PepScan.Changed",
  "status": "Pending",
  "partnerId": "30dee145-b6a2-4058-8dc3-ac4000dee91f",
  "createdAt": "2021-11-22T10:51:53.597-05:00",
  "resources": [
    "core/v1/cm/customers/9052b6a5-3f09-41d1-b526-ade80104eb79"
  ],
  "details": []
}

To retrieve the results of the OFAC and PEP scans, call GET core/v1/cm/customers/{id}, where id is the customer ID in the resources attribute of both events.

In this example, the customer ID is 9052b6a5-3f09-41d1-b526-ade80104eb79

Copy

Get customer details

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
26
27
28
29
{
  "id": "9052b6a5-3f09-41d1-b526-ade80104eb79",
  "cifNumber": "32653745014",
  "classification": "Personal",
  "status": "Active",
  "ofac": "Clear",
  "pepScan": "Clear",
  "name": {
    "firstName": "Peter",
    "lastName": "Griffin",
    "fullName": "Peter Griffin"
  },
  "profile": {
    "regO": false,
    "citizenshipCountryCode": "US",
    "politicallyExposedPerson": false,
    "enableBackupWithholding": false,
    "taxIdType": "Ssn",
    "taxId": "119988776",
    "birthDate": "1953-09-22",
    "riskRating": "Low"
  },
  "createdAt": "2021-11-22T10:49:58.843-05:00",
  "lastModifiedAt": "2021-11-22T10:51:49.5299112-05:00",
  "partnerId": "30dee145-b6a2-4058-8dc3-ac4000dee91f",
  "dueDiligence": {
    "annualIncome": 0
  }
}

3. Add details to the customer record

Next, you need to add the customer address and phone number. You can also add the customer email and identification information. Once you add this initial information, if needed you add more information, such as a mailing address. This tutorial will cover adding the address and phone number only. These details are considered primary information. If you add a second address, this is secondary.

b. To add an address and phone number to the customer record

Use the customer ID returned when you create the customer record to call POST /core/v1/cm/customers/{id}/addresses to add the customer address. The first address you add is the primary address.

Copy

Add customer address

1
2
3
4
5
6
7
8
9
10
11
POST /core/v1/cm/customers/9052b6a5-3f09-41d1-b526-ade80104eb79/addresses
{
  "addressType": "Home",
  "classification": "Residential",
  "isPrimary": true,
  "street1": "123 Any St",
  "city": "Anywhere",
  "state": "NY",
  "postalCode": "12345",
  "countryCode": "US"
}

Call POST /core/v1/cm/customers/{id}/phones to add the customer phone number. The first phone number you add is the primary phone number.

Copy

Add customer phone number

1
2
3
4
5
6
 POST /core/v1/cm/customers/9052b6a5-3f09-41d1-b526-ade80104eb79/phones
{
  "isPrimary": true,
  "phoneType": "Mobile",
  "phoneNumber": "2015552345"
}

The onboarding process is considered complete when the address and phone records have been added.