Getting Started Guides

Get Started: Create a Beneficial Owner for a Business Customer

Create a Beneficial Owner for a Customer Account. Beneficial Owners can be created for Business Customers only.

In this guide, you’ll learn how to:

Obtain the ID of the Business Customer Account.
Gather the required information for the Beneficial Owner.
Create the Beneficial Owner.
Retrieve the Beneficial Owner.

Before You Start

Sandbox Account: Sign up for a RocketKOR sandbox account. When your sandbox account is created, one or more Service Accounts will be created for your Business Account. A Service Account is a non-human user of a Business Account that performs functions (such as creating transactions) via the RocketKOR APIs on behalf of the Business Account.

Authentication: Before you can call the APIs, you must authenticate a Service Account by exchanging the account’s API key and secret for an access token.

Customer Account: Ensure the Business Customer has an active Customer Account.

Step 1: Obtain the Business Customer ID

Obtain the ID of the Business Customer Account that you’re creating a Beneficial Owner for. This must be a Business Customer, not an Individual Customer.

You can search for the Customer Account based on filters such as the account type, business name, email, and phone number.

Filter	Description
search	Perform a full-text search on the Customer’s ID, name, phone number, and email address. The following fields are included in the search. ID Searches the id field. Name Searches the businessName field. Email Searches the primaryEmail field for the primary contact for the Customer Account. Phone Number Searches the contacts.primaryPhoneNumber field for the primary contact for the Customer Account.
name	Business name (businessName).
primaryEmail	Primary email address (contacts.primaryEmail) for the primary contact for the Customer Account.
externalId	Your organization’s external reference number for the Customer.
primaryPhoneNumber	Primary phone number (contacts.primaryPhoneNumber) for the primary contact for the Customer Account.
createdAtFrom, createdAtTo	Date the Customer Account was created.
timeZone	Time zone for the createdAtFrom and createdAtTo filters.
type	Type of Customer Account (BUSINESS).
status	Status of the Customer Account (ACTIVE, SUSPENDED).
cityName	Customer’s city.
countryCode	Customer’s country code.
zipCode	Customer’s zip code or postal code.
sort, page, size	Pagination fields (sort response by any field, page number to return, and maximum number of results to return per page).

API Reference

List All Customers

Endpoint

GET /v1/customers

Response Example

Returns an array of Business Customer objects, based on the request filters. Make a note of the Customer Account id. You’ll need this ID in step 3 when you create the Beneficial Owner.

				
					{
  "id": "69248436-39f5-4074-9823-76d2580c82a6",
  "status": "ACTIVE",
  "type": "BUSINESS",
  "businessName": "ACME",
  "contacts": [
    {
      "firstName": "Jack",
      "lastName": "Smith",
      "primary": true,
      "primaryPhoneNumber": {
        "number": "+14151234",
        "type": "WORK"
      },
      "primaryEmail": {
        "value": "jsmith@acme.com"
      }
    }
  ],
  ...
}

Step 2: Gather the Required Beneficial Owner Information

Ensure you have the following details for the Beneficial Owner. You’ll need this information to create a Beneficial Owner in the next step.

Beneficial Owner’s first name
Beneficial Owner’s last name

Step 3: Create the Beneficial Owner

Create the Beneficial Owner. At a minimum, the request must include the following information. You can also include additional details such as the Beneficial Owner’s phone number, email, and address.

Parameter	Description
firstName	Beneficial Owner’s first name.
lastName	Beneficial Owner’s last name.

API Reference

Create a Beneficial Owner

Endpoint

POST /v1/customers/{customerId}/beneficiaries

In the request, pass the Customer Account id from step 1 to the customerId parameter.

Request Example

				
					{
  "firstName": "Natalie",
  "lastName": "Smith"
}

Response Example

Returns the Beneficial Owner object. The ID of the Customer Account to which the Beneficial Owner is attached is returned as the parentId.

Make a note of the Beneficial Owner id. You’ll need this ID in step 4 when you retrieve the Beneficial Owner.

				
					{
  "parentId": "69248436-39f5-4074-9823-76d2580c82a6",
  "id": "997dec9d-afcb-4843-a9e3-5333b6228229",
  "firstName": "Natalie",
  "lastName": "Smith",
  ...
}

Step 4: Retrieve the Beneficial Owner

Retrieve the Beneficial Owner you created in the previous step.

API Reference

Retrieve a Beneficial Owner

Endpoint

GET /v1/customers/{customerId}/beneficiaries/{beneficiaryId}

In the request:

Pass the Customer Account id from step 1 to the customerId parameter.
Pass the Beneficial Owner id from step 3 to the beneficiaryId parameter.

Response Example

Returns the Beneficial Owner object.

				
					{
  "parentId": "69248436-39f5-4074-9823-76d2580c82a6",
  "id": "997dec9d-afcb-4843-a9e3-5333b6228229",
  "firstName": "Natalie",
  "lastName": "Smith",
  ...
}

Get Started: Create a Beneficial Owner for a Business Customer

Before You Start

Step 1: Obtain the Business Customer ID

API Reference

Endpoint

Response Example

Step 2: Gather the Required Beneficial Owner Information

Step 3: Create the Beneficial Owner

API Reference

Endpoint

Request Example

Response Example

Step 4: Retrieve the Beneficial Owner

API Reference

Endpoint

Response Example

ON THIS PAGE