Beneficial Owner Object (Customer Account)

The Beneficial Owner object represents a Beneficial Owner that has been created for a Business Customer Account. This object provides detailed information for the Beneficial Owner.

Attributes

parentId

string (UUID)

ID of the Customer Account to which the Beneficial Owner belongs.

string (UUID)

ID of the Beneficial Owner.

firstName

string, min length: 1, max length: 40

Beneficial Owner’s first name.

middleName

string, min length: 1, max length: 40

Beneficial Owner’s middle name.

lastName

string, min length: 1, max length: 40

Beneficial Owner’s last name.

sex

string enum, values: MALE, FEMALE, NONBINARY

Beneficial Owner’s sex.

primaryPhoneNumber

object

Beneficial Owner’s primary phone number.

number

string

Phone number. Can be entered in any of the following formats:

[+][country code][phone number including area code] (example: +14151234)
[country code][phone number including area code] (example: 14151234)
[phone number including area code] (example: 4151234)

The phone number will be converted to E.164 format (example: +14151234).

type

string enum, values: WORK, HOME, MOBILE

Type of phone number.

provider

string, min length: 1, max length: 40

Phone provider.

extension

string, min length: 1, max length: 10

Phone extension.

verified

boolean

Whether the phone number has been verified through Identity Verification (IDV).

primaryEmail

object

Beneficial Owner’s primary email address.

value

string (email), max length: 320

Email address.

verified

boolean

Whether the email address has been verified through Identity Verification (IDV).

dateOfBirth

string (date), format: yyyy-MM-dd

Beneficial Owner’s date of birth.

placeOfBirth

object

Beneficial Owner’s place of birth.

city

string, max length: 60

City.

countryCode

string, min length: 3, max length: 3

Country code. Must be an ISO 3166-1 uppercase alpha 3-character country code. For example, the United States is USA and Canada is CAN.

socialId

string, max length: 50

Beneficial Owner’s unique national identifier, such as a Social Security Number (SSN). Responses include a truncated value only.

socialIdCountryCode

string, min length: 3, max length: 3

Country where the social ID was granted. Required if socialId is provided. Must be an ISO 3166-1 uppercase alpha 3-character country code. For example, the United States is USA and Canada is CAN.

citizenshipCountryCode

string, min length: 3, max length: 3

Country where the Beneficial Owner holds citizenship. Must be an ISO 3166-1 uppercase alpha 3-character country code. For example, the United States is USA and Canada is CAN.

title

string, max length: 100

Beneficial Owner’s title at the business.

ownershipPercentage

number, max length: 100

Percentage of the business owned by the Beneficial Owner.

controller

boolean

Whether the Beneficial Owner exercises significant control over the business. For example, the Beneficial Owner may be the CEO, General Partner, or Treasurer.

addresses

array

Beneficial Owner addresses.

The Beneficial Owner can have multiple addresses for each address type (MAILING, PHYSICAL, and SHIPPING).
A primary address must be specified for each address type added to the Beneficial Owner’s profile.
- Only one primary address can be specified for each address type.
- If a primary address is not specified for an address type, the first address of this type will be set as the primary address.
- If multiple addresses exist for an address type and the primary address is removed (and another address is not explicitly set as primary), another address of the same type will be set as the primary address.

type

string enum, values: MAILING, PHYSICAL, SHIPPING

Type of address. The following values are supported:

MAILING Address used for mail.
PHYSICAL Physical location where the Beneficial Owner resides. Cannot be a post office (PO) box.
SHIPPING Address used for packages or shipments.

name

object

Name of the contact person for shipments. Required if type is SHIPPING. Ignored for other address types.

firstName

string, min length: 1, max length: 40

Contact person’s first name.

middleName

string, min length: 1, max length: 40

Contact person’s middle name.

lastName

string, min length: 1, max length: 40

Contact person’s last name.

streetLine1

string, min length: 1, max length: 50

First line of the street address.

streetLine2

string, min length: 1, max length: 50

Second line of the street address.

streetLine3

string, min length: 1, max length: 50

Third line of the street address.

streetLine4

string, min length: 1, max length: 50

Fourth line of the street address. Only used for issued cards.

streetLine5

string, min length: 1, max length: 50

Fifth line of the street address. Only used for issued cards.

apartmentNumber

string

Apartment number.

cityName

string, min length: 1, max length: 25

City.

stateCode

string, min length: 2, max length: 3

State, province, or territory. Required if country is USA or CAN. Must be an ISO 3166-2 uppercase alpha 2-character or 3-character country subdivision code (for example, Missouri is MO).

countryCode

string, min length: 3, max length: 3

Country code. Must be an ISO 3166-1 uppercase alpha 3-character country code. For example, the United States is USA and Canada is CAN.

zipCode

string, min length: 1, max length: 10

Zip code or postal code. Required if countryCode is USA or CAN. For US addresses, must be a valid value of 5 digits (example: 63368) or 5 digits-4 digits (example: 63368-5555). Can be alphanumeric for other countries.

primary

boolean

Whether this is the primary address for this address type. A primary address must be specified for each address type added to the Beneficial Owner profile.

verified

boolean

Whether this address has been verified through Identity Verification (IDV).

verificationStatus

object

Current Identity Verification (IDV) status of the Beneficial Owner.

status

string enum, values: UNVERIFIED, PROCESSING, APPROVED, REVIEW, DECLINED, RESTRICTED

IDV status of the account. Possible values are:

UNVERIFIED The account has not yet been verified.
PROCESSING The account’s IDV application is currently being processed.
APPROVED The account has been verified successfully.
REVIEW A manual review of the IDV application is required.
DECLINED The account’s IDV application has been denied.
RESTRICTED The account has been verified with restrictions.

reason

string

Reason for the account’s IDV status.

updatedAt

string (date-time), format: yyyy-MM-dd’T’HH:mm:ss.SSSz

Date and time the account’s IDV status was last updated.

updatedBy

object

Entity that last updated the account’s IDV status.

string (UUID)

ID of the entity. Will be blank if updatedBy.type is internal.

type

string enum, values: employee, internal, kor_employee, service-account

Type of entity. The following values are supported:

employee Team Member using the RocketKOR Portal.
internal Internal service call.
kor_employee Rocket Financial employee.
service-account Service Account using APIs.

verificationStatusHistory

array

History of IDV status changes for the Beneficial Owner. The most recent status is shown first.

status

string enum, values: UNVERIFIED, PROCESSING, APPROVED, REVIEW, DECLINED, RESTRICTED

IDV status of the account. Possible values are:

UNVERIFIED The account has not yet been verified.
PROCESSING The account’s IDV application is currently being processed.
APPROVED The account has been verified successfully.
REVIEW A manual review of the IDV application is required.
DECLINED The account’s IDV application has been denied.
RESTRICTED The account has been verified with restrictions.

reason

string

Reason for the account’s IDV status.

updatedAt

string (date-time), format: yyyy-MM-dd’T’HH:mm:ss.SSSz

Date and time the account’s IDV status was last updated.

updatedBy

object

Entity that last updated the account’s IDV status.

string (UUID)

ID of the entity. Will be blank if updatedBy.type is internal.

type

string enum, values: employee, internal, kor_employee, service-account

Type of entity. The following values are supported:

employee Team Member using the RocketKOR Portal.
internal Internal service call.
kor_employee Rocket Financial employee.
service-account Service Account using APIs.

createdBy

string

Entity that created the Beneficial Owner.

string (UUID)

ID of the entity. Will be blank if createdBy.type is internal.

type

string enum, values: employee, internal, kor_employee, service-account

Type of entity. The following values are supported:

employee Team Member using the RocketKOR Portal.
internal Internal service call.
kor_employee Rocket Financial employee.
service-account Service Account using APIs.

createdAt

string (date-time)

Date and time the Beneficial Owner was created in the RocketKOR system.

updatedBy

string

Entity that last updated the Beneficial Owner.

string (UUID)

ID of the entity. Will be blank if updatedBy.type is internal.

type

string enum, values: employee, internal, kor_employee, service-account

Type of entity. The following values are supported:

employee Team Member using the RocketKOR Portal.
internal Internal service call.
kor_employee Rocket Financial employee.
service-account Service Account using APIs.

updatedAt

string (date-time)

Date and time the Beneficial Owner was last updated.

Beneficial Owner Object

				
					{
  "parentId": "string(UUID)",
  "id": "string(UUID)",
  "firstName": "string",
  "middleName": "string",
  "lastName": "string",
  "sex": "string",
  "primaryPhoneNumber": {
    "number": "string",
    "type": "WORK | HOME | MOBILE",
    "provider": "string",
    "extension": "string",
    "verified": boolean
  },
  "primaryEmail": {
    "value": "string",
    "verified": boolean
  },
  "dateOfBirth": "string",
  "placeOfBirth": {
    "city": "string",
    "countryCode": "string"
  },
  "socialId": "string",
  "socialIdCountryCode": "string",
  "citizenshipCountryCode": "string"
  "title": "string",
  "ownershipPercentage": number,
  "controller": boolean,
  "addresses": [
    {
      "type": "string",
      "streetLine1": "string",
      "streetLine2": "string",
      "streetLine3": "string",
      "streetLine4": "string",
      "streetLine5": "string",
      "apartmentNumber": "string",
      "cityName": "string",
      "stateCode": "string",
      "countryCode": "string",
      "zipCode": "string",
      "primary": boolean,
      "verified": boolean
    }
  ],
  "verificationStatus": {
    "status": "UNVERIFIED | PROCESSING | APPROVED | RESTRICTED | REVIEW | DECLINED",
    "reason": "string",
    "updatedAt": "string(date-time)",
    "updatedBy": {
      "id": "string(UUID)",
      "type": "type": "employee | internal | kor_employee | service-account"
    }
  },
  "verificationStatusHistory": [
    {
      "status": "UNVERIFIED | PROCESSING | APPROVED | RESTRICTED | REVIEW | DECLINED",
      "reason": "string",
      "updatedAt": "string(date-time)",
      "updatedBy": {
        "id": "string(UUID)",
        "type": "employee | internal | kor_employee | service-account"
      }
    }
  ],
  "createdBy": {
    "id": "string(UUID)",
    "type": "employee | internal | kor_employee | service-account"
  },
  "createdAt": "string(date-time)",
  "updatedBy": {
    "id": "string(UUID)",
    "type": "employee | internal | kor_employee | service-account"
  },
  "updatedAt": "string(date-time)"
}