Add Related Person

curl --request POST \
  --url https://api.rolla.xyz/api/v1/external/accounts/{accountId}/related-persons \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "id": "<string>",
  "firstName": "John",
  "lastName": "Doe",
  "roles": [],
  "email": "jsmith@example.com",
  "phone": "<string>",
  "dateOfBirth": "1990-01-15",
  "ownershipPercentage": 50,
  "currentAddress": {
    "street": "123 Main Street",
    "city": "Lagos",
    "state": "Lagos",
    "postalCode": "100001",
    "country": "NG"
  },
  "sourceOfWealthExplanation": "<string>",
  "taxId": "440301199209153216",
  "bvn": "<string>",
  "nin": "<string>"
}
'

import requests

url = "https://api.rolla.xyz/api/v1/external/accounts/{accountId}/related-persons"

payload = {
    "id": "<string>",
    "firstName": "John",
    "lastName": "Doe",
    "roles": [],
    "email": "jsmith@example.com",
    "phone": "<string>",
    "dateOfBirth": "1990-01-15",
    "ownershipPercentage": 50,
    "currentAddress": {
        "street": "123 Main Street",
        "city": "Lagos",
        "state": "Lagos",
        "postalCode": "100001",
        "country": "NG"
    },
    "sourceOfWealthExplanation": "<string>",
    "taxId": "440301199209153216",
    "bvn": "<string>",
    "nin": "<string>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    id: '<string>',
    firstName: 'John',
    lastName: 'Doe',
    roles: [],
    email: 'jsmith@example.com',
    phone: '<string>',
    dateOfBirth: '1990-01-15',
    ownershipPercentage: 50,
    currentAddress: {
      street: '123 Main Street',
      city: 'Lagos',
      state: 'Lagos',
      postalCode: '100001',
      country: 'NG'
    },
    sourceOfWealthExplanation: '<string>',
    taxId: '440301199209153216',
    bvn: '<string>',
    nin: '<string>'
  })
};

fetch('https://api.rolla.xyz/api/v1/external/accounts/{accountId}/related-persons', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.rolla.xyz/api/v1/external/accounts/{accountId}/related-persons",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'id' => '<string>',
    'firstName' => 'John',
    'lastName' => 'Doe',
    'roles' => [
        
    ],
    'email' => 'jsmith@example.com',
    'phone' => '<string>',
    'dateOfBirth' => '1990-01-15',
    'ownershipPercentage' => 50,
    'currentAddress' => [
        'street' => '123 Main Street',
        'city' => 'Lagos',
        'state' => 'Lagos',
        'postalCode' => '100001',
        'country' => 'NG'
    ],
    'sourceOfWealthExplanation' => '<string>',
    'taxId' => '440301199209153216',
    'bvn' => '<string>',
    'nin' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.rolla.xyz/api/v1/external/accounts/{accountId}/related-persons"

	payload := strings.NewReader("{\n  \"id\": \"<string>\",\n  \"firstName\": \"John\",\n  \"lastName\": \"Doe\",\n  \"roles\": [],\n  \"email\": \"jsmith@example.com\",\n  \"phone\": \"<string>\",\n  \"dateOfBirth\": \"1990-01-15\",\n  \"ownershipPercentage\": 50,\n  \"currentAddress\": {\n    \"street\": \"123 Main Street\",\n    \"city\": \"Lagos\",\n    \"state\": \"Lagos\",\n    \"postalCode\": \"100001\",\n    \"country\": \"NG\"\n  },\n  \"sourceOfWealthExplanation\": \"<string>\",\n  \"taxId\": \"440301199209153216\",\n  \"bvn\": \"<string>\",\n  \"nin\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.rolla.xyz/api/v1/external/accounts/{accountId}/related-persons")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"id\": \"<string>\",\n  \"firstName\": \"John\",\n  \"lastName\": \"Doe\",\n  \"roles\": [],\n  \"email\": \"jsmith@example.com\",\n  \"phone\": \"<string>\",\n  \"dateOfBirth\": \"1990-01-15\",\n  \"ownershipPercentage\": 50,\n  \"currentAddress\": {\n    \"street\": \"123 Main Street\",\n    \"city\": \"Lagos\",\n    \"state\": \"Lagos\",\n    \"postalCode\": \"100001\",\n    \"country\": \"NG\"\n  },\n  \"sourceOfWealthExplanation\": \"<string>\",\n  \"taxId\": \"440301199209153216\",\n  \"bvn\": \"<string>\",\n  \"nin\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.rolla.xyz/api/v1/external/accounts/{accountId}/related-persons")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"id\": \"<string>\",\n  \"firstName\": \"John\",\n  \"lastName\": \"Doe\",\n  \"roles\": [],\n  \"email\": \"jsmith@example.com\",\n  \"phone\": \"<string>\",\n  \"dateOfBirth\": \"1990-01-15\",\n  \"ownershipPercentage\": 50,\n  \"currentAddress\": {\n    \"street\": \"123 Main Street\",\n    \"city\": \"Lagos\",\n    \"state\": \"Lagos\",\n    \"postalCode\": \"100001\",\n    \"country\": \"NG\"\n  },\n  \"sourceOfWealthExplanation\": \"<string>\",\n  \"taxId\": \"440301199209153216\",\n  \"bvn\": \"<string>\",\n  \"nin\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Related person added successfully",
  "data": {
    "id": "<string>",
    "firstName": "John",
    "lastName": "Doe",
    "roles": [
      "Beneficial Owner"
    ],
    "email": "jsmith@example.com",
    "phone": "<string>",
    "dateOfBirth": "1990-01-15",
    "ownershipPercentage": 50,
    "currentAddress": {
      "street": "123 Main Street",
      "city": "Lagos",
      "state": "Lagos",
      "postalCode": "100001",
      "country": "NG"
    },
    "sourceOfWealthExplanation": "<string>",
    "taxId": "440301199209153216",
    "bvn": "<string>",
    "nin": "<string>"
  }
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

POST

accounts

{accountId}

related-persons

Add Related Person

curl --request POST \
  --url https://api.rolla.xyz/api/v1/external/accounts/{accountId}/related-persons \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "id": "<string>",
  "firstName": "John",
  "lastName": "Doe",
  "roles": [],
  "email": "jsmith@example.com",
  "phone": "<string>",
  "dateOfBirth": "1990-01-15",
  "ownershipPercentage": 50,
  "currentAddress": {
    "street": "123 Main Street",
    "city": "Lagos",
    "state": "Lagos",
    "postalCode": "100001",
    "country": "NG"
  },
  "sourceOfWealthExplanation": "<string>",
  "taxId": "440301199209153216",
  "bvn": "<string>",
  "nin": "<string>"
}
'

import requests

url = "https://api.rolla.xyz/api/v1/external/accounts/{accountId}/related-persons"

payload = {
    "id": "<string>",
    "firstName": "John",
    "lastName": "Doe",
    "roles": [],
    "email": "jsmith@example.com",
    "phone": "<string>",
    "dateOfBirth": "1990-01-15",
    "ownershipPercentage": 50,
    "currentAddress": {
        "street": "123 Main Street",
        "city": "Lagos",
        "state": "Lagos",
        "postalCode": "100001",
        "country": "NG"
    },
    "sourceOfWealthExplanation": "<string>",
    "taxId": "440301199209153216",
    "bvn": "<string>",
    "nin": "<string>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    id: '<string>',
    firstName: 'John',
    lastName: 'Doe',
    roles: [],
    email: 'jsmith@example.com',
    phone: '<string>',
    dateOfBirth: '1990-01-15',
    ownershipPercentage: 50,
    currentAddress: {
      street: '123 Main Street',
      city: 'Lagos',
      state: 'Lagos',
      postalCode: '100001',
      country: 'NG'
    },
    sourceOfWealthExplanation: '<string>',
    taxId: '440301199209153216',
    bvn: '<string>',
    nin: '<string>'
  })
};

fetch('https://api.rolla.xyz/api/v1/external/accounts/{accountId}/related-persons', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.rolla.xyz/api/v1/external/accounts/{accountId}/related-persons",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'id' => '<string>',
    'firstName' => 'John',
    'lastName' => 'Doe',
    'roles' => [
        
    ],
    'email' => 'jsmith@example.com',
    'phone' => '<string>',
    'dateOfBirth' => '1990-01-15',
    'ownershipPercentage' => 50,
    'currentAddress' => [
        'street' => '123 Main Street',
        'city' => 'Lagos',
        'state' => 'Lagos',
        'postalCode' => '100001',
        'country' => 'NG'
    ],
    'sourceOfWealthExplanation' => '<string>',
    'taxId' => '440301199209153216',
    'bvn' => '<string>',
    'nin' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.rolla.xyz/api/v1/external/accounts/{accountId}/related-persons"

	payload := strings.NewReader("{\n  \"id\": \"<string>\",\n  \"firstName\": \"John\",\n  \"lastName\": \"Doe\",\n  \"roles\": [],\n  \"email\": \"jsmith@example.com\",\n  \"phone\": \"<string>\",\n  \"dateOfBirth\": \"1990-01-15\",\n  \"ownershipPercentage\": 50,\n  \"currentAddress\": {\n    \"street\": \"123 Main Street\",\n    \"city\": \"Lagos\",\n    \"state\": \"Lagos\",\n    \"postalCode\": \"100001\",\n    \"country\": \"NG\"\n  },\n  \"sourceOfWealthExplanation\": \"<string>\",\n  \"taxId\": \"440301199209153216\",\n  \"bvn\": \"<string>\",\n  \"nin\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.rolla.xyz/api/v1/external/accounts/{accountId}/related-persons")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"id\": \"<string>\",\n  \"firstName\": \"John\",\n  \"lastName\": \"Doe\",\n  \"roles\": [],\n  \"email\": \"jsmith@example.com\",\n  \"phone\": \"<string>\",\n  \"dateOfBirth\": \"1990-01-15\",\n  \"ownershipPercentage\": 50,\n  \"currentAddress\": {\n    \"street\": \"123 Main Street\",\n    \"city\": \"Lagos\",\n    \"state\": \"Lagos\",\n    \"postalCode\": \"100001\",\n    \"country\": \"NG\"\n  },\n  \"sourceOfWealthExplanation\": \"<string>\",\n  \"taxId\": \"440301199209153216\",\n  \"bvn\": \"<string>\",\n  \"nin\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.rolla.xyz/api/v1/external/accounts/{accountId}/related-persons")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"id\": \"<string>\",\n  \"firstName\": \"John\",\n  \"lastName\": \"Doe\",\n  \"roles\": [],\n  \"email\": \"jsmith@example.com\",\n  \"phone\": \"<string>\",\n  \"dateOfBirth\": \"1990-01-15\",\n  \"ownershipPercentage\": 50,\n  \"currentAddress\": {\n    \"street\": \"123 Main Street\",\n    \"city\": \"Lagos\",\n    \"state\": \"Lagos\",\n    \"postalCode\": \"100001\",\n    \"country\": \"NG\"\n  },\n  \"sourceOfWealthExplanation\": \"<string>\",\n  \"taxId\": \"440301199209153216\",\n  \"bvn\": \"<string>\",\n  \"nin\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Related person added successfully",
  "data": {
    "id": "<string>",
    "firstName": "John",
    "lastName": "Doe",
    "roles": [
      "Beneficial Owner"
    ],
    "email": "jsmith@example.com",
    "phone": "<string>",
    "dateOfBirth": "1990-01-15",
    "ownershipPercentage": 50,
    "currentAddress": {
      "street": "123 Main Street",
      "city": "Lagos",
      "state": "Lagos",
      "postalCode": "100001",
      "country": "NG"
    },
    "sourceOfWealthExplanation": "<string>",
    "taxId": "440301199209153216",
    "bvn": "<string>",
    "nin": "<string>"
  }
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

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.

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

Owners must be at least 18. 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.

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.<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

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

{
  "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. Nigerian residents send `nin` instead. Can be patched later via Update Related Person
`bvn` / `nin`	string	No	Nigerian identifiers. `nin` (11 digits) is what Nigerian residents send in place of `taxId`

Authorizations

X-API-Key

string

header

required

Your Rolla API key

Path Parameters

accountId

string<uuid>

required

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

Body

application/json

string

firstName

string

Example:

"John"

lastName

string

Example:

"Doe"

roles

enum<string>[]

Available options:

Beneficial Owner,

Director

string<email>

phone

string

dateOfBirth

string

Example:

"1990-01-15"

ownershipPercentage

number

Required range: 0 <= x <= 100

currentAddress

object

Show child attributes

sourceOfWealthExplanation

string

taxId

string

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

string

Bank Verification Number (11 digits). Nigerian residents only.

nin

string

National Identification Number (11 digits). Nigerian residents only; accepted in place of taxId.

Response

Related person added successfully

success

boolean

Example:

true

message

string

Example:

"Related person added successfully"

data

object

Show child attributes

Overview

Banks

Account Lookup

Transactions

Wallet

Beneficiaries

Teams

Account Onboarding

Webhooks

Add Related Person

Required before submission

Government identifier

Example Request

Example Response

Parameters

Authorizations

Path Parameters

Body

Response

​Required before submission

​Government identifier

​Example Request

​Example Response

​Parameters

Authorizations

Path Parameters

Body

Response

Required before submission

Government identifier

Example Request

Example Response

Parameters