Owners & chains

An owner is any entity that holds equity: a pension fund, an asset manager, an institution, a holding company or an individual. Owners carry an owner_id, a name, a country and a type. Crucially, they also form chains.

Ownership is a tree, not a list

Real-world positions are layered. A family owns through a holding company; an asset manager's stake is the sum of dozens of individual funds; a pension fund reports through regional sub-entities. Dataflow preserves this structure:

• Owners can have a parent (parent_id), forming chains from the ultimate owner down to individual funds.
• A position can have sub-holdings: the positions reported underneath it by child entities.

Tier-one vs base

When you query holdings you choose the depth:

• Tier-one: one row per top-level owner, the view you'd print as "largest shareholders". Sub-structure is aggregated into the parent.
• Base: the full chain expanded, every reporting entity, including intermediate holding companies and individual funds.

On the REST side these are separate endpoints (…/tier-one and …/base). On the MCP side, tools return tier-one rows with a has_sub_holdings flag, and get_sub_holdings drills one level at a time, recursively, since each returned row may itself have children.

Finding owners

• MCP: search_owners resolves free-text names. By default it returns top-level entities; set only_top_level: false to include sub-entities.
• REST: filter any ownership endpoint by owner-ids, or pull an owner's whole portfolio by filtering on the owner side.