Onboarding Customers

In this tutorial we explore the customer onboarding process. The onboarding process includes creating a customer record and adding additional information such as address and phone information. Since all customers are automatically scanned for regulatory compliance purposes, we will also register relevant webhooks to receive status updates to the customer record. Before starting this tutorial, please make sure you have the following:

API credentials
Partner ID

Get an Access Token

Before calling the COS API you must first request an access token. Once the access token has been obtained it is recommended that it is cached for the lifetime of the token. If the API starts to return a 401 response code, it is likely that your token has expired and you need to obtain a new one. More details can be found here.

Register Webhooks

Webhooks allow us to receive notifications when certain events occur within COS. After we submit the request to onboard a customer in the step below, we will want to stay informed on the result of the compliance scan as well as the creation of the customer record. For that you will need to call the webhook registration endpoint and indicate you wish to receive certain events.

The Core.Customer.Onboarded event will notify you in the event a customer record has been created.

POST /webhooks/v1/registrations
{
  "partnerId": "00000000-0000-0000-0000-000000000000",
  "eventName": "Core.Customer.Onboarded",
  "registrationType": "Push", 
  "callbackUrl": "https://cos.yourcompanysite.com/core-events"
}

The Core.Customer.Ofac.Changed event will notify you in the event a customer's OFAC status has been updated.

POST /webhooks/v1/registrations
{
  "partnerId": "00000000-0000-0000-0000-000000000000",
  "eventName": "Core.Customer.Ofac.Changed",
  "registrationType": "Push", 
  "callbackUrl": "https://cos.yourcompanysite.com/core-events"
}

The Core.Customer.PepScan.Changed event will notify you in the event a customer's PEP status has been updated.

POST /webhooks/v1/registrations
{
  "partnerId": "00000000-0000-0000-0000-000000000000",
  "eventName": "Core.Customer.PepScan.Changed",
  "registrationType": "Push", 
  "callbackUrl": "https://cos.yourcompanysite.com/core-events"
}

To learn more about webhook registrations click here. For a full listing of available customer webhook events click here.

Onboard Customer

In this scenario, you'll be onboarding Peter Griffin by creating a customer record, followed by adding address and phone information.

POST /core/v1/cm/customers
{
  "partnerId": "00000000-0000-0000-0000-000000000000",
  "name": {
    "firstName": "Bob",
    "lastName": "Smith"
  },
  "classification": "Personal",
  "profile": {
    "regO": false,
    "politicallyExposedPerson": false,
    "taxIdType": "Ssn",
    "taxId": "119988776",
    "birthDate": "1953-09-22",
    "riskRating": "Low"
  }
}

🚧
It is highly recommended that you include idempotency key in your request header. This will provide duplicate protection in the event of a failure. Read more about idempotency keys here.

COS will provide a response similar to the one below for a successful request.

{
  "id": "9052b6a5-3f09-41d1-b526-ade80104eb79",
  "cifNumber": "32653745014",
  "classification": "Personal",
  "status": "Active",
  "ofac": "Pending",
  "pepScan": "Pending",
  "name": {
    "firstName": "Bob",
    "lastName": "Smith",
    "fullName": "Bob Smith"
  },
  "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": "00000000-0000-0000-0000-000000000000"
}

{
  "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": []
}

COS will perform OFAC and PEP compliance scans for the customer once the record is created. There may be instances where the results of a scan warrant manual review by the Bank's Anti-Money Laundering (AML) team. If your intention is to open an account for the customer, then the customer's OFAC and PEP statuses must first be Clear. Once the scanning is complete, COS will fire the OFAC and Pep Scan changed webhook events:

{
  "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": []
}

{
  "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": []
}

The resources in the two events above contain the customer ID. You can use the customer ID with GET core/v1/cm/customers/{id} to view the result of each scan:

{
  "id": "9052b6a5-3f09-41d1-b526-ade80104eb79",
  "cifNumber": "32653745014",
  "classification": "Personal",
  "status": "Active",
  "ofac": "Clear",
  "pepScan": "Clear",
  "name": {
    "firstName": "Bob",
    "lastName": "Smith",
    "fullName": "Bob Smith"
  },
  "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
  }
}

In the response above, the ofac and pepScan fields show a "Clear" status.

Next, you'll need to perform two additional requests to add the customer's address and phone number using the customer ID that was returned from completing the steps above. For customers, the first address, phone, email, and identification is considered the primary. Once a primary record is added, secondary records can be created, such as a mailing address.

Here's a sample request to add an address using the customer ID that we received from the successful onboarding response:

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"
}

Here's a sample request to add a phone number using the customer ID that we received from the successful onboarding response:

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

The onboarding process is considered complete once the address and phone records have been added. An account can now be opened for the customer.

❗️
Your program may require you to populate additional customer information during the onboarding process. These fields are part of the dueDiligence array in the POST core/v1/cm/customers operation.