Persons API

Manage directors, shareholders, and ultimate beneficial owners

Persons represent individuals associated with an entity, such as directors, shareholders, and ultimate beneficial owners (UBOs). Each person can have multiple roles within an entity.

Person Object

{
  "id": "per_abc123",
  "party_id": "pty_xyz789",
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@example.com",
  "date_of_birth": "1985-03-15",
  "nationality": "US",
  "roles": ["director", "shareholder"],
  "kyc_status": "pending",
  "address": {
    "street1": "123 Main Street",
    "street2": "Suite 100",
    "city": "New York",
    "state": "NY",
    "country": "US",
    "postcode": "10001"
  }
}

Important: When you include shareholder in the roles array, the person is marked as a potential shareholder. To actually allocate shares, you must create a shareholding via the Shares API using the party_id returned in the response. A person only appears as a shareholder in the list after they have been allocated shares.

Person Roles

Role	Description
`director`	Company director with management responsibilities
`shareholder`	Potential shareholder - use Shares API to allocate shares and complete the role
`ubo`	Ultimate beneficial owner (typically 25%+ ownership)

Address Object

Field	Type	Required	Description
`street1`	string	Yes	Primary street address
`street2`	string	No	Secondary address line (apartment, suite, etc.)
`city`	string	Yes	City or town
`state`	string	No	State, province, or region
`country`	string	Yes	Country (ISO 3166-1 alpha-2 code recommended)
`postcode`	string	No	Postal or ZIP code

Address Requirements: Most jurisdictions require addresses for directors and UBOs. Use the /catalog endpoint to check which roles require addresses for your specific jurisdiction and product type. Missing required addresses will be reported by the /entities/:id/requirements endpoint.

KYC Statuses

Status	Description
`pending`	KYC verification not yet started
`current`	KYC verification is current and valid
`expired`	KYC verification has expired and needs renewal

Endpoints

Working with Shareholders

How shareholder roles work: Including shareholder in the roles array when creating a person marks them as a potential shareholder. The person will only appear in the persons list with the shareholder role after you allocate shares to them via the Shares API.

Here's the complete workflow to set up a shareholder:

Shareholder Setup Workflow

// 1. Create a share class (if not already created)
POST /api/v1/entities/{entityId}/share-classes
{
  "name": "Ordinary Shares",
  "currency": "USD",
  "par_value": 1.00,
  "voting_rights": true,
  "dividend_rights": true
}
// Response: { "data": { "id": "sc_abc123", ... } }

// 2. Create a person (shareholder role is optional here)
POST /api/v1/entities/{entityId}/persons
{
  "first_name": "John",
  "last_name": "Smith",
  "email": "john@example.com",
  "roles": ["director"]
}
// Response: { "data": { "id": "per_xyz789", "party_id": "pty_abc123", ... } }
// IMPORTANT: Save the party_id for the next step!

// 3. Allocate shares - THIS makes them a shareholder
POST /api/v1/entities/{entityId}/shareholdings
{
  "party_id": "pty_abc123",
  "share_class_id": "sc_abc123",
  "shares_held": 1000
}
// Now when you GET /persons, John will appear with roles: ["director", "shareholder"]

Key Points

The party_id (not the person id) is used to create shareholdings
A person becomes a shareholder when they have at least one active shareholding
The shareholder role in the persons list is derived from the shareholdings data