> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rolla.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Add Related Person
> Adds a beneficial owner or director to a business account's application. Each related person must complete identity verification (via a KYC link) before the application can be submitted.
Adds a beneficial owner or director to a business account's application. Every related person must complete identity verification — via a [KYC link](/api-reference/endpoint/accounts/kyc-link) — before the application can be submitted.
## Required before submission
A business must declare **at least one** beneficial owner or director. For each person:
| Group | Required |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| Details | `firstName`, `lastName`, `email`, `phone`, `dateOfBirth`, `sourceOfWealthExplanation` |
| `currentAddress` | `street`, `city`, `state`, `postalCode`, `country` |
| Identifier | `taxId` — the person's government identifier. Nigerian residents supply `nin` (11 digits) instead |
| Documents | `proof_of_address`, `source_of_wealth_doc` — upload with their `relatedPersonId` |
| Verification | a completed [KYC link](/api-reference/endpoint/accounts/kyc-link) |
Owners must be at least 18. [Get Requirements](/api-reference/endpoint/accounts/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.
| Country of residence | Field | Format | Example |
| -------------------- | ------- | ----------------------------------- | -------------------- |
| Nigeria | `nin` | 11 digits | `12345678901` |
| Mainland China | `taxId` | 18-character resident ID | `440301199209153216` |
| Hong Kong | `taxId` | HKID | `UH123456(A)` |
| United States | `taxId` | SSN or ITIN | `123456789` |
| Elsewhere | `taxId` | national ID or tax number as issued | — |
`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..taxId` in [Get Requirements](/api-reference/endpoint/accounts/requirements) and blocks submission. Supplying the wrong **format** for the country is only caught later, when the USD account is issued.
## Example Request
```bash theme={null}
curl -X POST "https://api.rolla.xyz/api/v1/external/accounts/eec3cbed-79d8-4370-87a0-b6be9e287337/related-persons" \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"firstName": "Jane",
"lastName": "Doe",
"roles": ["Beneficial Owner", "Director"],
"email": "jane@betalogistics.com",
"phone": "+13025550124",
"dateOfBirth": "1985-09-21",
"taxId": "123456789",
"ownershipPercentage": 60,
"currentAddress": {
"street": "5 Oak St",
"city": "Wilmington",
"state": "DE",
"postalCode": "19801",
"country": "US"
}
}'
```
## Example Response
```json theme={null}
{
"success": true,
"message": "Related person added successfully",
"data": {
"id": "a3d4f21e-f499-488f-8508-43228dfea485",
"firstName": "Jane",
"lastName": "Doe",
"roles": ["Beneficial Owner", "Director"],
"email": "jane@betalogistics.com",
"phone": "+13025550124",
"dateOfBirth": "1985-09-21",
"ownershipPercentage": 60,
"currentAddress": {
"street": "5 Oak St",
"city": "Wilmington",
"state": "DE",
"postalCode": "19801",
"country": "US"
}
}
}
```
## Parameters
| Field | Type | Required | Description |
| --------------------------- | --------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `firstName` | string | Yes | First name |
| `lastName` | string | Yes | Last name |
| `roles` | string\[] | No | `Beneficial Owner` and/or `Director` (defaults to `Beneficial Owner`) |
| `email` | string | Yes | Email address |
| `phone` | string | Yes | Phone number |
| `dateOfBirth` | string | Yes | Date of birth (`YYYY-MM-DD`) |
| `ownershipPercentage` | number | No | Ownership stake, 0–100 |
| `currentAddress` | object | Yes | Residential address (`street`, `city`, `state`, `postalCode`, `country`) |
| `sourceOfWealthExplanation` | string | No | Free-text source of wealth |
| `taxId` | string | Not on this call — required before submission | The person's government identifier, in [the format their country of residence issues](#government-identifier). Nigerian residents send `nin` instead. Can be patched later via [Update Related Person](/api-reference/endpoint/accounts/update-related-person) |
| `bvn` / `nin` | string | No | Nigerian identifiers. `nin` (11 digits) is what Nigerian residents send in place of `taxId` |
## OpenAPI
````yaml POST /accounts/{accountId}/related-persons
openapi: 3.1.0
info:
title: Rolla Developer API
description: >-
API for programmatic transaction management on the Rolla platform. Monetary
`amount` fields use the smallest unit of the referenced currency unless an
endpoint says otherwise (e.g. NGN = kobo, USD = cents, where **100 cents =
USD 1.00**).
version: 1.0.0
servers:
- url: https://api.rolla.xyz/api/v1/external
description: Production server
security:
- apiKeyAuth: []
paths:
/accounts/{accountId}/related-persons:
post:
summary: Add Related Person
description: >-
Adds a beneficial owner or director to a business account's application.
Each related person must complete identity verification (via a KYC link)
before the application can be submitted.
operationId: addAccountRelatedPerson
parameters:
- name: accountId
in: path
required: true
description: >-
Identifier of an account owned by the same user as your API key's
business
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RelatedPerson'
responses:
'201':
description: Related person added successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: Related person added successfully
data:
$ref: '#/components/schemas/RelatedPerson'
'400':
description: Validation error or non-business account
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Account not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
RelatedPerson:
type: object
properties:
id:
type: string
firstName:
type: string
example: John
lastName:
type: string
example: Doe
roles:
type: array
items:
type: string
enum:
- Beneficial Owner
- Director
email:
type: string
format: email
phone:
type: string
dateOfBirth:
type: string
example: '1990-01-15'
ownershipPercentage:
type: number
minimum: 0
maximum: 100
currentAddress:
$ref: '#/components/schemas/BusinessAddress'
sourceOfWealthExplanation:
type: string
taxId:
type: string
description: >-
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: 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: '440301199209153216'
bvn:
type: string
description: Bank Verification Number (11 digits). Nigerian residents only.
nin:
type: string
description: >-
National Identification Number (11 digits). Nigerian residents only;
accepted in place of `taxId`.
Error:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
BusinessAddress:
type: object
properties:
street:
type: string
example: 123 Main Street
city:
type: string
example: Lagos
state:
type: string
example: Lagos
postalCode:
type: string
example: '100001'
country:
type: string
example: NG
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Your Rolla API key
````