Equity

The equity API allows you to manage share ownership for a company. You can issue new shares, transfer shares between shareholders, perform buybacks and retirements, and execute stock splits. The API also provides position tracking and cap table generation.

Endpoints

List Transaction Types

GET /api/v2/equity/transaction-types

Returns the available equity transaction types.

Response

{
  "transaction_types": [
    { "value": "ISSUANCE", "label": "ISSUANCE" },
    { "value": "TRANSFER", "label": "TRANSFER" },
    { "value": "BUYBACK", "label": "BUYBACK" },
    { "value": "RETIREMENT", "label": "RETIREMENT" },
    { "value": "SPLIT", "label": "SPLIT" },
    { "value": "CONVERSION", "label": "CONVERSION" }
  ]
}

List Share Classes

GET /api/v2/equity/share-classes

Returns the available share class types.

Response

{
  "share_classes": [
    { "value": "ORDINARY", "label": "ORDINARY" },
    { "value": "CLASS_A", "label": "CLASS_A" },
    { "value": "CLASS_B", "label": "CLASS_B" },
    { "value": "CLASS_C", "label": "CLASS_C" },
    { "value": "PREFERRED", "label": "PREFERRED" },
    { "value": "OTHER", "label": "OTHER" }
  ]
}

List Transactions

GET /api/v2/equity/transactions

Retrieves a paginated list of equity transactions.

Query Parameters

Response

{
  "data": [
    {
      "id": 1,
      "created_at": "2024-06-01T10:00:00Z",
      "created_by_id": 7,
      "updated_at": null,
      "updated_by_id": null,
      "client_account_id": 7,
      "transaction_date": "2024-06-01",
      "transaction_type": "ISSUANCE",
      "transaction_group_id": "a1b2c3d4",
      "business_partner_id": 56,
      "share_class": "ORDINARY",
      "quantity": "1000.000000",
      "price_per_share": "100.000000",
      "notes": "Initial share issuance",
      "split_ratio_numerator": null,
      "split_ratio_denominator": null
    }
  ],
  "meta": {
    "page": 1,
    "pages": 1,
    "per_page": 50,
    "records": 1
  }
}

Get Transaction

GET /api/v2/equity/transactions/{id}

Retrieves a specific equity transaction by ID.

Response

Returns a single transaction object (same shape as the list response items).

Issue Shares

POST /api/v2/equity/transactions/issue

Issues new shares to a shareholder.

Request Body

Example Request

{
  "client_account_id": 7,
  "business_partner_id": 56,
  "share_class": "ORDINARY",
  "quantity": "1000",
  "price_per_share": "100",
  "transaction_date": "2024-06-01",
  "notes": "Initial share issuance"
}

Response

Returns the created transaction with status 201 Created.

Transfer Shares

POST /api/v2/equity/transactions/transfer

Transfers shares from one shareholder to another.

Request Body

Example Request

{
  "client_account_id": 7,
  "from_business_partner_id": 56,
  "to_business_partner_id": 78,
  "share_class": "ORDINARY",
  "quantity": "200",
  "price_per_share": "150",
  "transaction_date": "2024-09-15"
}

Response

Returns the created transaction with status 201 Created.

Validation

• from_business_partner_id and to_business_partner_id must be different
• The seller must hold enough shares of the specified class (returns 400 with an insufficient shares error otherwise)

Buyback Shares

POST /api/v2/equity/transactions/buyback

Records a company buyback of its own shares from a shareholder.

Request Body

Response

Returns the created transaction with status 201 Created.

Validation

• from_business_partner_id and company_business_partner_id must be different
• The shareholder must hold enough shares of the specified class

Retire Shares

POST /api/v2/equity/transactions/retire

Retires (cancels) shares held by the company.

Request Body

Response

Returns the created transaction with status 201 Created.

Validation

• The company must hold enough shares of the specified class (typically acquired via buyback)

Stock Split

POST /api/v2/equity/transactions/split

Executes a stock split (forward or reverse) for a shareholder’s position.

Request Body

Example Request

A 2-for-1 forward split of 500 shares:

{
  "client_account_id": 7,
  "business_partner_id": 56,
  "share_class": "ORDINARY",
  "old_quantity": "500",
  "new_quantity": "1000",
  "transaction_date": "2024-12-01",
  "notes": "2:1 forward stock split"
}

Response

Returns the created transaction with status 201 Created.

Get Positions

GET /api/v2/equity/positions

Returns current equity positions (shareholdings) aggregated from all transactions.

Query Parameters

Response

[
  {
    "business_partner_id": 56,
    "share_class": "ORDINARY",
    "quantity": "800.000000",
    "cost_basis": "80000.000000",
    "average_price": "100.000000"
  }
]

Get Cap Table

GET /api/v2/equity/cap-table

Generates a capitalization table showing the ownership structure of the company.

Query Parameters

Response

Returns the generated cap table object.

Attributes

Transaction

Position

Error Responses

Related Resources

• Business Partners — shareholders are represented as business partners
• Shareholder Register Report — RF-1086 regulatory reporting based on equity data