Shares API

Manage share classes and shareholdings for entities

The Shares API allows you to manage share classes and shareholdings for your entities. Share classes define the types of shares an entity can issue (e.g., Ordinary Shares, Preferred Shares), while shareholdings record the actual allocation of shares to shareholders.

Share Class Object

{
  "id": "sc_abc123",
  "entity_id": "ent_xyz789",
  "name": "Ordinary Shares",
  "currency": "USD",
  "par_value": 1.00,
  "voting_rights": true,
  "dividend_rights": true,
  "details": {},
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Shareholding Object

{
  "id": "sh_def456",
  "entity_id": "ent_xyz789",
  "party_id": "pty_abc123",
  "party_type": "PERSON",
  "party_name": "John Smith",
  "share_class_id": "sc_abc123",
  "share_class_name": "Ordinary Shares",
  "shares_held": 1000,
  "date_acquired": "2024-01-15",
  "date_disposed": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Share Class Properties

Property	Description
`name`	Name of the share class (e.g., "Ordinary Shares", "Class A")
`currency`	Currency code for the share class (e.g., "USD", "GBP")
`par_value`	Par value per share (nominal value)
`voting_rights`	Whether shares of this class have voting rights
`dividend_rights`	Whether shares of this class have dividend rights

Important: Creating a shareholding is what makes a party a shareholder. The party_id from the Parties API response is used to link the party to their shares. Once a shareholding exists, the party will appear with the "shareholder" role when listing parties.

Typical Workflow

Create a share class for your entity (e.g., "Ordinary Shares")
Create parties via the Parties API (shareholder role in request is optional)
Use the party_id from the party response to create shareholdings
The party now appears as a shareholder when you list parties
Query shareholdings to view the cap table

Share Classes

Shareholdings

Complete Example

Here's a complete example showing how to set up a company with two shareholders in a 60/40 split:

Complete Shareholding Setup

// 1. Create a share class
const shareClass = await fetch('/api/v1/entities/{entityId}/share-classes', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Ordinary Shares',
    currency: 'USD',
    par_value: 1.00,
    voting_rights: true,
    dividend_rights: true
  })
});

// 2. Create first shareholder (60%)
const person1 = await fetch('/api/v1/entities/{entityId}/parties', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    party_type: 'person',
    first_name: 'Alice',
    last_name: 'Johnson',
    email: 'alice@example.com',
    roles: ['director', 'shareholder']
  })
});

// 3. Allocate 600 shares to Alice
await fetch('/api/v1/entities/{entityId}/shareholdings', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    party_id: person1.data.party_id,
    share_class_id: shareClass.data.id,
    shares_held: 600
  })
});

// 4. Create second shareholder (40%)
const person2 = await fetch('/api/v1/entities/{entityId}/parties', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    party_type: 'person',
    first_name: 'Bob',
    last_name: 'Williams',
    email: 'bob@example.com',
    roles: ['shareholder']
  })
});

// 5. Allocate 400 shares to Bob
await fetch('/api/v1/entities/{entityId}/shareholdings', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    party_id: person2.data.party_id,
    share_class_id: shareClass.data.id,
    shares_held: 400
  })
});

// 6. View the cap table
const capTable = await fetch('/api/v1/entities/{entityId}/shareholdings', {
  headers: { 'Authorization': 'Bearer sk_live_...' }
});