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

Add a beneficial owner to a customer record

POST /core/v1/cm/customers/{customerId}/beneficial-owners

Updates a business customer record with information about the business beneficial owner

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

entityName

string

Optional 

Name of the business if opening a business account. 255 character maximum.

prefix

string

Optional 

Prefix for name

firstName

string

Required  

Account holder first name. 100 characters maximum.

middleName

string

Optional 

Account holder middle name. 50 characters maximum.

lastName

string

Required  

Account holder last name. 100 characters maximum.

suffix

string

Optional 

Suffix for name

preferredName

string

Optional 

Customer preferred name. 255 character maximum.

fullName

string

Optional 

Customer's entire name including middle initial. 255 character maximum.

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

regO

boolean

Optional 

Pertains to loans issued to executive officers, directors, and principal shareholders of member banks. True if the customer is one of them. Otherwise false.

This attribute is not relevant for a business entity.

citizenshipCountryCode

string

Optional 

Country of citizenship (2 characters)

politicallyExposedPerson

boolean

Optional 

Politically exposed person (PEP). True if PEP, otherwise false

This attribute is not relevant for a business entity.

enableBackupWithholding

boolean

Optional 

Enable to allow withholding taxes on interest earned. True when enabled, otherwise false.

backupWithholdingPercent

integer

Conditional 

If Backup Withholding is enabled, the percentage to withhold taxes on interest earned

taxIdType

string

Required  

Tax ID type for the entity:

  • Ssn

  • Ein

  • Itin

  • Vat

  • Foreign

taxId

string

Required  

Tax ID number. 9 character minimum. 20 character maximum.

birthDate

string

Optional 

Date of birth in the format "yyyy-mm-dd"

This attribute is not relevant for a business entity.

dateFormed

string

Optional 

Date when legal entity was formed. In the format "yyyy-mm-dd".

Not relevant for an individual.

entityType

string

Optional 

Business entity legal classification. Also called Customer entity type.

riskRating

string

Required  

Customer risk rating:

  • Low

  • Medium

  • High

ownershipType

string

Optional 

  • Exempt

  • Excluded

  • NonProfit

  • LegalEntity

primaryOwnerCustomerId

string

Optional 

Customer ID of the primary owner of a business account

parentEntityId

string

Optional 

The business customer related to the customer being created. Used when a customer is a sole proprietorship or doing DBA.

dateOfDeath

string

Optional 

Indicates the date of a customer's passing, should that occur

privacyOptOut

boolean

Optional 

Customer opts out of information sharing. True when the customer opts out, otherwise false.

dueDiligence

object

Conditional 

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

employmentStatus

string

How and if the customer is employed:

  • Employed

  • SelfEmployed

  • Retired

  • Unemployed

  • Student

occupation

string

  • Executive

  • Sales

  • Consulting

  • Government

  • Healthcare

  • FinanceAccounting

  • Technology

  • ScienceEngineering

  • FoodServices

  • LegalServices

  • Manufacturing

  • Other

occupationDescription

string

Any further details needed about the customer's occupation.

Up to 255 characters.

industry

string

  • Agriculture

  • Mining

  • Utilities

  • Construction

  • Manufacturing

  • ChemicalManufacturing

  • MerchantWholesale

  • Automotive

  • RetailFurnishing

  • RetailElectronics

  • RetailHome

  • RetailFood

  • HealthStores

  • Gasoline

  • RetailClothing

  • RetailSporting

  • RetailNonStore

  • Transportation

  • Publishing

  • Finance

  • RealEstate

  • RentalServices

  • ProfessionalNonLegal

  • Accounting

  • Travel

  • EducationalMedical

  • PerformingArts

  • RecreationGambling

  • FoodService

  • Maintenance

  • Laundry

  • ReligiousCharity

  • PublicAdministration

incomeSource

string

  • Salary

  • SelfEmployed

  • Inheritance

  • Investments

  • Retirement

  • RentalIncome

  • GovernmentBenefits

  • FamilySupport

incomeState

string

State where customer earns income

incomeCountryCode

string

2-letter code of the country where the customer earns income

employer

string

Name of customer's employer

employerState

string

State where customer employer is based

employerCountryCode

string

2-letter code of the country where the customer's employer is based

sourceOfFunds

string

  • SelfEmployed

  • GeneralEmployee

  • SeniorExecutive

  • Retired

  • Homemaker

  • InheritanceGift

  • Investment

  • Salary

  • BusinessOwner

  • Alimony

  • Retirement

  • Lottery

  • Annuity

  • TrustIncome

  • RealEstate

  • GovernmentBenefits

  • LegalSettlement

wealthSource

string

  • Salary

  • SelfEmployed

  • Inheritance

  • FamilySupport

  • Investments

  • Retirement

  • RentalIncome

  • GovernmentBenefits

  • BusinessSale

  • Other

wealthSourceDescription

string

Further details about the customer's source of wealth.

255 characters maximum.

annualIncome

integer

Customer annual income

businessDueDiligence

object

Optional 

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

natureOfBusiness

string

Optional 

xxx. nn characters maximum

naics

string

Optional 

Business's North American Industry Classification System code

merchantCategoryCode

string

Optional 

ISO-defined 4-digit number that classifies a business by the goods they sell or the services they provide. nn characters maximum

businessUrl

string

Optional 

xxx. nn characters maximum

relationshipFormationDate

string

Optional 

xxx. nn characters maximum

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

addressType

string

Required  

What this is the address of

  • Home

  • Work

  • Other

classification

string

Required  

What kind of address this is:

  • Residential

  • Business

  • PoBox

  • Rural

  • Military

  • Other

isPrimary

string

Required  

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

street1

string

Required  

Primary location details of account holder, for instance, street name, house/building number, PO box.

street2

string

Optional 

Additional address information.

street3

string

Optional 

Additional address information.

city

string

Optional 

City full name. 50 character maximum.

state

string

Optional 

State name. 10 character maximum.

postalCode

string

Optional 

Postal code, also known as ZIP code

countryCode

string

Required  

2-letter ISO country code

primaryPhone

object

Main phone number for the customer

isPrimary

string

Required  

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

phoneType

string

Required  

The phone number calls a:

  • Home

  • Mobile

  • Work

  • Fax

phoneNumber

string

Required  

10-digit phone number with no spaces or other characters

extension

string

Optional 

If the phone rings a switchboard, the entity's direct extension.

notes

string

Optional 

Additional phone information. 255 character maximum.

primaryEmail

string

Optional 

Main email address for the customer

isPrimary

string

Required  

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

emailType

string

Required  

Email address is:

  • Personal

  • Work

  • Other

emailAddress

string

Required  

Customer's primary email address. This must be a minimum of 6 characters.

primaryIdentification

string

Optional 

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

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

Required  

The kind of ID:

  • 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

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.

entityName

string

Name of the business if opening a business account

prefix

string

Prefix for name

firstName

string

Account holder first name. 100 characters maximum.

middleName

string

Account holder middle name. 50 characters maximum.

lastName

string

Account holder last name. 100 characters maximum.

suffix

string

Suffix for name

preferredName

string

Customer preferred name

fullName

string

Concatenation of firstName, middleName, and lastName.

profile

object

Customer banking-relevant information

regO

boolean

Pertains to loans issued to executive officers, directors, and principal shareholders of member banks. True if the customer is one of them. Otherwise false.

This attribute is not relevant for a business entity.

citizenshipCountryCode

string

Country of citizenship (2 characters)

politicallyExposedPerson

boolean

Politically exposed person (PEP). True if the customer is a PEP, otherwise false.

enableBackupWithholding

boolean

Enable to allow withholding taxes on interest earned. True when enabled, otherwise false.

backupWithholdingPercent

integer

If Backup Withholding is enabled, the percentage to withhold taxes on interest earned

taxIdType

string

Tax ID type for the entity:

  • Ssn

  • Ein

  • Itin

  • Vat

  • Foreign

taxId

string

Tax ID number

birthDate

string

Date of birth

dateFormed

string

Date when legal entity was formed. In the format "yyyy-mm-dd".

Not relevant for an individual.

entityType

string

Business entity legal classification. Also called Customer entity type.

riskRating

string

Customer risk rating: Low, Medium, High

ownershipType

string

  • Exempt

  • Excluded

  • NonProfit

  • LegalEntity

primaryOwnerCustomerId

string

Customer ID of the primary owner of a business account

parentEntityId

string

The business customer related to the customer being created. Used when a customer is a sole proprietorship or doing DBA.

dateOfDeath

string

Indicates the date of a customer's passing, should that occur

privacyOptOut

boolean

Customer opts out of information sharing. True when the customer opts out, otherwise false.

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.

employmentStatus

string

Choose from:

  • Employed

  • SelfEmployed

  • Retired

  • Unemployed

  • Student

occupation

string

  • Executive

  • Sales

  • Consulting

  • Government

  • Healthcare

  • FinanceAccounting

  • Technology

  • ScienceEngineering

  • FoodServices

  • LegalServices

  • Manufacturing

  • Other

occupationDescription

string

Any further details needed about the customer's occupation.

industry

string

  • Agriculture

  • Mining

  • Utilities

  • Construction

  • Manufacturing

  • ChemicalManufacturing

  • MerchantWholesale

  • Automotive

  • RetailFurnishing

  • RetailElectronics

  • RetailHome

  • RetailFood

  • HealthStores

  • Gasoline

  • RetailClothing

  • RetailSporting

  • RetailNonStore

  • Transportation

  • Publishing

  • Finance

  • RealEstate

  • RentalServices

  • ProfessionalNonLegal

  • Accounting

  • Travel

  • EducationalMedical

  • PerformingArts

  • RecreationGambling

  • FoodService

  • Maintenance

  • Laundry

  • ReligiousCharity

  • PublicAdministration

incomeSource

string

  • Salary

  • SelfEmployed

  • Inheritance

  • Investments

  • Retirement

  • RentalIncome

  • GovernmentBenefits

  • FamilySupport

incomeState

string

State where customer earns income

incomeCountryCode

string

2-letter code of the country where the customer earns income

employer

string

Name of customer's employer

employerState

string

State where customer employer is based

employerCountryCode

string

2-letter code of the country where the customer's employer is based

sourceOfFunds

string

  • SelfEmployed

  • GeneralEmployee

  • SeniorExecutive

  • Retired

  • Homemaker

  • InheritanceGift

  • Investment

  • Salary

  • BusinessOwner

  • Alimony

  • Retirement

  • Lottery

  • Annuity

  • TrustIncome

  • RealEstate

  • GovernmentBenefits

  • LegalSettlement

wealthSource

string

  • Salary

  • SelfEmployed

  • Inheritance

  • FamilySupport

  • Investments

  • Retirement

  • RentalIncome

  • GovernmentBenefits

  • BusinessSale

  • Other

wealthSourceDescription

string

Further details about the customer's source of wealth.

annualIncome

integer

Any further details needed about the customer's occupation.

businessDueDiligence

object

Details for due diligence compliance for a business entity.

natureOfBusiness

string

xxx. nn characters maximum

naics

string

Optional 

Business's North American Industry Classification System code

merchantCategoryCode

string

xxx. nn characters maximum

businessUrl

string

xxx. nn characters maximum

relationshipFormationDate

string

xxx. nn characters maximum

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

id

string

COS ID for the primary address 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

string

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

status

string

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

  • Inactive

  • Active

classification

string

What kind of address this is:

  • Residential

  • Business

  • PoBox

  • Rural

  • Military

  • Other

addressType

string

What this is the address of

  • Home

  • Work

  • Other

street1

string

Primary location details of account holder, for instance, street name, house/building number, PO box.

street2

string

Additional address information.

street3

string

Additional address information.

city

string

City full name. 50 character maximum.

state

string

State name. 10 character maximum.

postalCode

string

Optional 

Postal code, also known as ZIP code

countryCode

string

2-letter ISO country code

createdAt

string

Time and date the primary address 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.

primaryEmail

object

Main email address for the customer

id

string

COS ID for the primary email 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

string

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

status

string

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

  • Inactive

  • Active

emailType

string

What this is the address of

  • Personal

  • Work

  • Other

emailAddress

string

Customer's primary email address

createdAt

string

Time and date the primary email address 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.

primaryIdentification

string

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

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.

primaryPhone

string

Main phone number for the customer

id

string

COS ID for the primary phone number 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.

status

string

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

  • Inactive

  • Active

phoneType

string

What this is the address of

  • Home

  • Mobile

  • Work

  • fax

isPrimary

string

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

phoneNumber

string

10-digit phone number with no spaces or other characters

extension

string

If the phone rings a switchboard, the entity's direct extension.

notes

string

Additional phone information. 255 character maximum.

createdAt

string

Time and date the phone number 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
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"
}

Add a beneficial owner to a customer record

/core/v1/cm/customers/{customerId}/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.

For credit BIN sponsorship, use this endpoint to associate commercial cardholders with their business employer. In this case, each cardholder is added as a beneficial owner resource, and you enter Auth User for the ownerTitle attribute.

Request attributes

customerId

string

Required  

Customer ID of the business customer record you're updating.

This is a GUID.

ownerCustomerId

string

Required  

Customer ID of the beneficial owner personal customer record you're adding as a beneficial owner resource.

This is a GUID.

ownerTitle

string

Required  

Title of the beneficial owner (For example, CEO, board member, owner).

For credit BIN sponsorship this is always Auth User.

50 characters maximum.

ownershipPercentage

number

Optional 

Percentage of the business this beneficial owner controls.

Enter the percentage in real numbers. For example, if you enter 0.20 it means 0.20%. If you enter 20, it means 20%.

Response attributes

id

string

ID of the beneficial owner record.

This is a GUID.

customerId

string

Customer ID of the customer record that was updated. This is the ID you used in the request path.

This is a GUID.

ownerCustomerId

string

Customer ID of the beneficial owner personal customer record you've added as a resource.

This is a GUID.

status

string

Status of the beneficial owner record:

  • Inactive

  • Active

ownerTitle

string

Title of the beneficial owner (For example, CEO, board member, owner).

For credit BIN sponsorship this is always Auth User.

partnerId

string

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

createdAt

string

Date and time the record was created. 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.

ownershipPercentage

number

Percentage of the business this beneficial owner controls
Copy

Request sample

curl -X POST 
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: Bearer <token>'
-d '{ \
{
  "ownerCustomerId": "262a2462-048e-4a8c-9ae0-1f0c9b59c11b",
  "ownerTitle": "CEO",
  "ownershipPercentage": 60%
}' 'https://sandbox.crbcos.com/Core/v1/cm/customers/650688ab-e728-4030-a73d-57f6c65e0899/beneficial-owners'
Copy

Response sample

{
  "id": "c8834eeb-b7e6-4578-b427-63d0768a684a",
  "customerId": "650688ab-e728-4030-a73d-57f6c65e0899",
  "ownerCustomerId": "262a2462-048e-4a8c-9ae0-1f0c9b59c11b",
  "status": "Active",
  "ownerTitle": "CEO",
  "partnerId": "afe55ce4-7770-4e50-9029-12b2e1655a61",
  "createdAt": "2024-01-07T08:13:08.464Z",
  "lastModifiedAt": "2024-01-07T08:13:08.464Z",
  "ownershipPercentage": 60%
}

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

How to add a beneficial owner resource to a customer record

 

Back to top