--- title: Onboard a customer slug: tutorials/api/customer-management/onboard-a-customer description: Describes the customer onboarding process and includes creating a customer record and adding relevant customer information. docTags: createdAt: 2024-08-12T13:30:09.439Z --- ## What you will learn ✅ How to create a new customer ✅ How to add relevant customer details, including customer address and phone number 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. :::hint{type="info"} Learn more about [customer management](docId\:Nt23Lv6UL3hwB2r5bz4K9). The tutorial assumes you have a knowledge of APIs and how they work. Refer to [API basics](docId\:pUTTCwQ5SKLzxYzIn5D1b) for more details. ::: The tutorial uses these API endpoints: | API | Description | | --------------------------------------------------------------------------------------- | ------------------------------------- | | [POST /core/v1/cm/customers](docId\:isgkj7NIS9jHmyu3UPUBk) | Create a new customer record | | [GET /core/v1/cm/customers/{customerId}](docId\:x36Ga61oFeFCQBnmUG0sS) | Retrieve customer information | | [POST /core/v1/cm/customers/{customerId}/addresses](docId\:tWpyIp5zxe-kjEJqEUqfc) | Add or edit the customer address | | [POST /core/v1/cm/customers/{customerId}/phones](docId:5bNWSnxsqTB_GtuntlnPW) | Add or edit the customer phone number | ## Before you begin Make sure you have: - [API credentials](docId\:wmg-1Fqwq3bj-D3c3HFfs) - Partner ID - [Registered](docId\:BN5XtgkJogBe-CtwomCbS) the following webhook events: | 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 | ## Create the customer record The customer record contains customer information. The customer record supports both classifications of types *Personal* or *Business*. Once onboarded, 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. :::hint{type="info"} To onboard a business customer, first create a personal customer record for the *primary owner *of that business. ::: :::::WorkflowBlock ::::WorkflowBlockItem Call `POST /core/v1/cm/customers`. For this call these attributes are required: :::hint{type="info"} A customer must have an identification document in their record, however this can be added as a separate call and is not required for the create customer call. ::: | 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 (`riskRating`)
- Tax ID and Tax ID type | :::hint{type="warning"} **IMPORTANT** We highly recommend you include an [idempotency key](docId\:xQC2lRsG0xVv_9NMkqxKk) in your request header to provide duplicate protection in the event of a failure. ::: ```curl 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. :::CodeblockTabs Onboarding a customer response body ```json {   "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" } ``` ::: :::: ::::WorkflowBlockItem The `Core.Customer.Onboarded` webhook event is triggered when the customer record is created. :::CodeblockTabs Customer onboarded event ```json {   "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": [] } ``` ::: Cross River scans a new customer record for OFAC and PEP compliance. :::hint{type="info"} 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. :::CodeblockTabs Customer OFAC scan changed ```json {   "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": [] } ``` ::: :::CodeblockTabs Customer PEP scan changed ```json {   "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": [] } ``` ::: :::: ::::WorkflowBlockItem 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** :::CodeblockTabs Get customer details ```curl {   "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   } } ``` ::: :::: ::::: ## Add details to the customer record Next, you need to add the customer address, phone number and identification information. You can also add the customer email. 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*. :::::WorkflowBlock ::::WorkflowBlockItem Use the `customerId` 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. :::CodeblockTabs Add customer address ```curl 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" } ``` ::: :::: ::::WorkflowBlockItem 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. :::CodeblockTabs Add customer phone number ```curl  POST /core/v1/cm/customers/9052b6a5-3f09-41d1-b526-ade80104eb79/phones {   "isPrimary": true,   "phoneType": "Mobile",   "phoneNumber": "2015552345" } ``` ::: :::: ::::WorkflowBlockItem Call `POST /core/v1/cm/customers/{customerId}/identifications` to add a physical ID to the customer record. What you are really doing is adding the metadata about the ID and not an image of the ID. You could also do this separately. See the [Add identification](docId\:Gk2cTwkzVsjNTRDhQ67E5) tutorial. :::hint{type="warning"} It is *mandatory* to have an identification record (such as a driver's license) associated with a customer record. ::: ```curl POST /core/v1/cm/customers/9052b6a5-3f09-41d1-b526-ade80104eb79/identifications { "isPrimary": true, "idNumber": "18e5b61d-fbac-4a52-9cce-3af544886199", "idType": "Other", "issuedDate": "2022-08-18", "expDate": "2027-08-18", "verifiedDate": "2025-08-18", "issuingAuthority": "Fintech", "issuingStateOrProvince": "NJ", "issuingCountryCode": "US" } ``` :::: ::::: The onboarding process is considered complete when the address, phone, and identification records have been added.