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",
  "person_id": "per_abc123",
  "shareholder_entity_id": null,
  "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 person a shareholder. The party_id from the Persons API response is used to link the person to their shares. Once a shareholding exists, the person will appear with the "shareholder" role when listing persons.

Typical Workflow

Create a share class for your entity (e.g., "Ordinary Shares")
Create persons via the Persons API (shareholder role in request is optional)
Use the party_id from the person response to create shareholdings
The person now appears as a shareholder when you list persons
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}/persons', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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}/persons', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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_...' }
});