Parties API

Manage directors, shareholders, UBOs, and corporate parties associated with an entity

A party is any individual or legal entity associated with a corporate entity in a defined role — director, shareholder, UBO, supervisor, member, or officer. All party types are managed through a single unified endpoint, with the party_type field distinguishing natural persons from companies and foundations.

party_type: "person" — natural individual
party_type: "corporate" — company or other incorporated body
party_type: "foundation" — private foundation

All party endpoints use parties:read / parties:write scopes. The partyId path parameter is always the party_id (pty_...) returned in create and list responses.

Party Roles

Role	Applies to	Description
`director`	person, corporate	Company director with management responsibilities
`shareholder`	person, corporate	Shareholder — use Shares API to allocate shares and activate this role
`ubo`	person	Ultimate beneficial owner (typically 25%+ ownership)
`member`	person, corporate	Council or board member (used in foundations)
`supervisor`	person, corporate	Supervisory board or oversight role
`officer`	person	Company officer (e.g. secretary, president)

Shareholder role: Adding shareholder to a party's roles registers them as a potential shareholder. The role only becomes active once you allocate shares via the Shares API using the party_id returned in the create response.

Endpoints

Party Utilities

These endpoints make it easy to re-use parties across entities — avoiding duplicate data entry when the same individual or company appears in multiple incorporations.

Related webhook events

Event	Fires when
party.added	A party (person, company, or foundation) is added to an entity. Payload includes `party_type` to distinguish.
party.updated	A party's details are updated.
party.removed	A party is removed from an entity.

Working with Shareholders

How the shareholder role works: Adding shareholder to a party's roles at creation marks them as a potential shareholder. They will only appear as an active shareholder after you allocate shares to them via the Shares API.

Shareholder setup workflow

// 1. Create a share class
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. Add the party
POST /api/v1/entities/{entityId}/parties
{
  "party_type": "person",
  "first_name": "John",
  "last_name": "Smith",
  "email": "john@example.com",
  "roles": ["director"]
}
// Response: { "data": { "party_id": "pty_abc123", ... } }
// Save party_id — it is the identifier used for shareholdings.

// 3. Allocate shares — this activates the shareholder role
POST /api/v1/entities/{entityId}/shareholdings
{
  "party_id": "pty_abc123",
  "share_class_id": "sc_abc123",
  "shares_held": 1000
}
// Now GET /parties returns John with roles: ["director", "shareholder"]