Skip to main content
POST
Add Related Person
Adds a beneficial owner or director to a business account’s application. Every related person must complete identity verification — via a KYC link — before the application can be submitted.

Mandatory and optional fields

A business must declare at least one beneficial owner or director. Unlike the other update endpoints, this one rejects an incomplete person. The fields marked Required below must be present in the request itself. The rest are accepted now and checked before the application can be submitted.

currentAddress

Required in the request, and all five fields must be present together.

Documents and verification

Both documents are mandatory before submission, uploaded with the person’s relatedPersonId: proof_of_address and source_of_wealth_doc. Each person must also complete a KYC link. Get Requirements reports anything outstanding per person under relatedPersons[].missingFields and relatedPersons[].missingDocuments.

Government identifier

Every person needs one, and our USD banking partner validates it in the format their country of residence issues — so the value differs per person, not per account.
nin is accepted as a taxId for people added before this field existed, so nothing needs re-sending. New integrations should use taxId.
A missing identifier is not rejected when you add the person — it surfaces as related_persons.<id>.taxId in Get Requirements and blocks submission. Supplying the wrong format for the country is only caught later, when the USD account is issued.

Example Request

Example Response

The stored record is the id plus exactly the fields you sent: anything you left out is absent until you supply it, and roles is filled in with ["Beneficial Owner"] when omitted. Use id as the personId on the update and delete calls, and as the relatedPersonId when uploading this person’s documents.

Errors

Parameters

Authorizations

X-API-Key
string
header
required

Your Rolla API key

Path Parameters

accountId
string<uuid>
required

Identifier of a business account owned by the same user as your API key's business

Body

application/json
firstName
string
required
Minimum string length: 1
Example:

"Jane"

lastName
string
required
Minimum string length: 1
Example:

"Doe"

email
string<email>
required

Where this person’s KYC link is sent

Example:

"jane@betalogistics.com"

phone
string
required

International format

Minimum string length: 1
Example:

"+13025550124"

dateOfBirth
string
required

YYYY-MM-DD. The person must be 18 or older

Example:

"1985-09-21"

currentAddress
object
required

Residential address. All-or-nothing: whenever the object is sent, every one of the five fields must be present.

roles
enum<string>[]

The person's capacities on the business. Defaults to ["Beneficial Owner"] when omitted or empty, so the stored record always has at least one role.

Available options:
Beneficial Owner,
Director
Example:
ownershipPercentage
number

Ownership stake as a percentage, not a fraction: send 60 for 60%. A value between 0 and 1 is rejected.

Required range: 0 <= x <= 100
Example:

60

sourceOfWealthExplanation
string

Free-text explanation of where the person’s wealth comes from. Accepted empty here; required before the application can be submitted.

Example:

"Salary and dividends from Beta Logistics LLC"

taxId
string | null

The person's government identifier, in the format their country of residence issues — Mainland China: 18-character resident ID; Hong Kong: HKID; United States: SSN or ITIN; elsewhere: the national ID or tax number as issued. Nigerian residents send nin instead. Required before the application can be submitted, and can be patched onto an existing person. The format is validated by the USD provider when the account is issued.

Example:

"123456789"

bvn
string | null

Bank Verification Number. Nigerian residents only; must be 11 digits when the person's currentAddress.country is NG.

Example:

"22345678901"

nin
string | null

National Identification Number, accepted in place of taxId for Nigerian residents; must be 11 digits when the person's currentAddress.country is NG.

Example:

"12345678901"

Response

Related person added successfully

status
integer
required
Example:

201

message
string
required
Example:

"Related person added successfully"

success
boolean
required
Example:

true

data
object
required

A beneficial owner or director on a business account’s application.