Customer management APIs

Use Cross River (CR) APIs to manage your customer information (called a customer record). You need a customer record, for example, to open a deposit account or create a debit card.

Customer management APIs are found in the core module of our COS sandbox.

Note

Get started with Cross River APIs.

This table presents Customer Management APIs that we describe in detail.

Action

API Call

Description

Onboard a customer POST /core/v1/cm/customers

Creates a new customer record

Add identification information to an existing customer

POST /core/v1/cm/customers/{customerId}/identifications/{id}

Updates a customer record with customer-identifying document metadata or other unique ID

Onboard a customer

/core/v1/cm/customers

Creates a new customer record.

The customer record is the primary resource that contains customer information and supports the classification of Personal or Business . Once onboarded, a customer can be associated with one or more accounts.

Important

Some customer endpoints include a dueDiligence resource that may or may not be required when onboarding personal customers. Your assigned compliance liaison communicates requirements for any Due Diligence fields during your onboarding process.

Request attributes

partnerId

string

Required  

Your ID in the CR system. This ID is in GUID format.

name

object

Account holder name in detail

classification

string

Required  

The classification type of the account being created:

  • Personal (an individual)

  • Business (a legal entity)

profile

object

Required  

Customer banking-relevant information

dueDiligence

object

Conditional 

Details for due diligence compliance for an individual customer. To be used when required.

businessDueDiligence

object

Optional 

Details for due diligence compliance for a business entity. To be used when required.

clientIdentifier

string

Optional 

Use this attribute to add your own unique identifying string to a payment call or COS record. This attribute is useful for idempotency purposes.

primaryAddress

object

Main address for the customer

primaryPhone

object

Main phone number for the customer

primaryEmail

string

Optional 

Main email address for the customer

primaryIdentification

string

Optional 

Identification metadata of customer-identifying documents, such as a driver's license or passport

Response attributes

id

string

The unique customer ID for the onboarded customer. This ID is in GUID format.

cifNumber

string

The Customer Identification File Number

classification

string

Classification type of the account being created:

  • Personal (an individual)

  • Business (a legal entity)

status

string

Status of the customer record:

  • Inactive

  • Active

ofac

string

Status of customer on OFAC list check:

  • Pending

  • Clear

  • Failed

  • Positive

  • Reviewing

pepScan

string

Status of customer on PEP list check:

  • Pending

  • Clear

  • Failed

  • Positive

  • Reviewing

internalList

string

Status of customer on internal CR list check:

  • Pending

  • Clear

  • Failed

  • Positive

  • Reviewing

name

object

Account holder name in detail.

profile

object

Customer banking-relevant information

createdAt

string

Date and time the customer was created

lastModifiedAt

string

Internal CR value. Date and time the database entry was last modified.

partnerId

string

Your ID in the CR system. This ID is in GUID format.

dueDiligence

object

Details for due diligence compliance for an individual customer.

businessDueDiligence

object

Details for due diligence compliance for a business entity.

clientIdentifier

string

Use this attribute to add your own unique identifying string to a payment call or COS record. This attribute is useful for idempotency purposes.

primaryAddress

object

Main address for the customer

primaryEmail

object

Main email address for the customer

primaryIdentification

string

Identification metadata of customer-identifying documents, such as a driver's license or passport

primaryPhone

string

Main phone number for the customer

Back to top

Copy
Sample request personal account
curl -X POST 
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: Bearer <token>'
-d '{ \
{
  "partnerId": "ad475a30-5c89-406d-9a3e-103aa38c3ba0",
  "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
  }
}' 'https://sandbox.crbcos.com/Core/v1/cm/customers'
Copy

Sample response

{
  "id": "49160e7c-6c94-4898-a7cc-5457b80a3307",
  "cifNumber": "136274839562",
  "classification": "Personal",
  "status": "Active",
  "name": {
    "prefix": "Mr.",
    "firstName": "John",
    "middleName": "Robert",
    "lastName": "Smith",
    "suffix": "Jr.",
    "preferredName": "Jim"
  },
  "profile": {
    "regO": false,
    "politicallyExposedPerson": false,
    "enableBackupWithholding": false,
    "taxIdType": "Ssn",
    "taxId": "123456789",
    "birthDate": "1965-09-15",
    "riskRating": "Low",
  },
  "createdAt": "2018-08-30T14:24:42.394Z",
  "lastModifiedAt": "2018-08-30T14:24:42.394Z",
  "partnerId": "ad475a30-5c89-406d-9a3e-103aa38c3ba0"
}

Add identification information to an existing customer

/core/v1/cm/customers/{customerId}/identifications/{id}

Adds unique identification metadata of customer-identifying documents to customer details. This could be an official ID such as a driver's license or passport. You can also add other information such as a token from a card payment processor, to associate the card with your customer.

Request attributes

customerId

string

Required  

The unique ID assigned to a customer when the customer record is created (POST /core/v1/cm/customers). You need this ID to take action for a specific customer. For example, when opening an account or adding an address to a customer record.

The ID is in GUID format.

isPrimary

boolean

Required  

True if this is the primary identification record for this customer. Otherwise, false.

idNumber

string

Required  

The identification number being added

idType

string

The kind of ID:

Required  

  • DriversLicense

  • Passport

  • IdCard

  • SocialSecurity

  • Other

issuedDate

string

Optional 

Date the ID was issued

expDate

string

Optional 

Date the ID expires

verifiedDate

string

Optional 

Date the identification was verified

issuingAuthority

string

Required  

The official authority that issued the ID. For example, the Department of Motor Vehicles.

issuingStateOrProvince

string

Optional 

State or province where the ID was issued

issuingCountryCode

string

Required  

Country where the ID was issued expressed as a 2-character code

Response attributes

id

string

COS ID for the identification record in GUID format

customerId

string

The unique ID assigned to a customer when the customer record is created (POST /core/v1/cm/customers). You need this ID to take action for a specific customer. For example, when opening an account or adding an address to a customer record.

The ID is in GUID format.

isPrimary

boolean

True if this is the primary identification record for this customer. Otherwise, false.

idNumber

string

The identification number of that was added to the customer record

status

string

The status of the identification record in COS Explorer. If you delete a record using Explorer the database record still exists, but with status Inactive.

  • Inactive

  • Active

idType

string

The kind of ID:

  • DriversLicense

  • Passport

  • IdCard

  • SocialSecurity

  • Other

issuedDate

string

Date the ID was issued yyyy-mm-dd

expDate

string

Date the ID expires yyyy-mm-dd

verifiedDate

string

Date the identification was verified

issuingAuthority

string

The official authority that issued the ID. For example, the Department of Motor Vehicles.

issuingStateOrProvince

string

State or province where the ID was issued

issuingCountryCode

string

Country where the ID was issued expressed as a 2-character code

createdAt

string

Time and date the ID information was added to the customer record. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

lastModifiedAt

string

Internal CR value. Date and time the database entry was last modified.

partnerId

string

Your ID in the CR system. This ID is in GUID format.

Back to top

Copy

Request sample

curl -X POST
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: Bearer <token>'
-d '{ \
  "isPrimary": true,
  "idNumber": "DL12345 67890 54321",
  "idType": "DriversLicense",
  "issuedDate": "2018-08-30",
  "expDate": "2023-08-30",
  "verifiedDate": "2018-08-30",
  "issuingAuthority": "NJMVC",
  "issuingStateOrProvince": "NJ",
  "issuingCountryCode": "US",
}' 'https://sandbox.crbcos.com/Core/v1/cm/customers/49160e7c-6c94-4898-a7cc-5457b80a3307/identifications'
Copy

Response sample

{
  "id": "6d3add34-0a1e-4a4e-9c7f-b00a0091e308",
  "customerId": "49160e7c-6c94-4898-a7cc-5457b80a3307",
  "isPrimary": true,
  "idNumber": "DL12345 67890 54321",
  "status": "Active",
  "idType": "DriversLicense",
  "issuedDate": "2018-08-30",
  "expDate": "2018-08-30",
  "issuingAuthority": "NJMVC",
  "issuingStateOrProvince": "NJ",
  "issuingCountryCode": "US",
  "createdAt": "2023-05-22T04:51:09.4656083-04:00",
  "lastModifiedAt": "2023-05-22T04:51:09.4656083-04:00",
  "partnerId": "ad475a30-5c89-406d-9a3e-103aa38c3ba0"
}

Associated webhook events

Event Name

Description

Core.Customer.Onboarded

New customer was onboarded

Core.Customer.Profile.Changed

Customer profile was changed

Core.Customer.Name.Changed

Customer name changed

Core.Customer.CifNumber.Changed

 

Core.Customer.Address.Added

Customer address was added

Core.Customer.Address.Changed

Customer address was changed

Core.Customer.Address.Removed

Customer address was removed

Core.Customer.Phone.Added

Customer phone number was added

Core.Customer.Phone.Changed

Customer phone number was changed

Core.Customer.Phone.Removed

Customer phone number was removed

Core.Customer.Identification.Added

Customer identification was added

Core.Customer.Identification.Changed

Customer identification changed

Core.Customer.Identification.Removed

Customer identification was removed

Core.Customer.Email.Added

Customer email was added

Core.Customer.Email.Changed

Customer email was changed

Core.Customer.Email.Removed

Customer email was removed

Core.Customer.Ofac.Changed

Customer OFAC scan resulted in a status change

Core.Customer.PepScan.Changed

Customer PEP Scan resulted in a status change

Back to top

Related topics

Customer management

COS error codes

Tutorials

How to onboard a customer

How to add an identification document to a customer record

 

Back to top