Ownership
Read a company's direct shareholders, trace its ownership chain with a shareholder graph, and retrieve its ultimate beneficial owners.
Kausate answers three ownership questions. Each takes a kausateId.
| Question | Product | Endpoint |
|---|---|---|
| Who holds shares in this company directly? | Company report | POST /v2/companies/report |
| Who owns it, level by level, up the chain? | Shareholder graph | POST /v2/companies/shareholder-graph |
| Who is recorded as its beneficial owner? | UBO report | POST /v2/companies/ubo |
Each jurisdiction guide lists which of these it supports.
Direct shareholders
A company report's relationships.shareholders lists the company's direct
holders: the people and companies holding its shares, with the number of
shares, percentage, share class and interest type where the register gives
them. See Company data model.
Shareholder graph
A shareholder graph starts at one company and follows each corporate
shareholder to its own shareholders, level by level. maxDepth sets how many
levels to follow: 3 by default, at most 7.
curl -X POST https://api.kausate.com/v2/companies/shareholder-graph \
-H "X-API-Key: $API_KEY" \
-H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-d '{"kausateId": "co_de_7aH2IUvdvC6XGzbUbSyhOU", "maxDepth": 3}'A deep graph can take a while, so order it asynchronously and poll
Get Shareholder Graph Order
or receive it by webhook. Add
includeIntermediateResult=true to the poll to see the graph built so far.
The synchronous endpoint returns one level only.
Read the graph
The completed order holds result.graph:
| Field | Meaning |
|---|---|
nodes | Every company and person in the graph. type is rootEntity, company, person, freeFloat or unknown. |
edges | One per holding. source is the company held and target the holder. |
rootCompanyId | The node of the company you ordered. |
stopReason | Why the graph ends. completed means every ownership chain was fully resolved. |
sources | Where each node's data comes from. |
An edge's data carries the holding: percentage, numberOfShares,
shareClass, interestType and whether the holding is direct or indirect.
A percentage can be exact or a range, such as more than 25 %.
Company and person nodes carry cumulativeOwnership: the share of the root
company they hold through every path in the graph. Where a company in the
graph has a kausateId, you can order its report or documents too. A
freeFloat node stands for publicly traded shares not held by a disclosed
shareholder, and an unknown node for ownership no disclosed shareholder
accounts for.
Any stopReason other than completed means the graph is partial: for
example max_depth_reached when owners continue beyond maxDepth,
budget_exhausted when the order's
maxCredits limit
left no room for another company, or insufficient_credits when your
organization ran out of credits on the way.
Extend a graph
Extend a completed graph to follow its owners further without ordering it
again. POST /v2/companies/shareholder-graph/{orderId}/extend takes
additionalDepth (1 by default, at most 7) and, optionally, the
extendNodeIds to continue from. Without them it continues from every company
that still has unfollowed owners.
An extension is charged per company it extends, at the price for that
company's jurisdiction. Send the same body to
POST /v2/companies/shareholder-graph/{orderId}/extend/quote first: it
returns the companies that would be extended, the credits for each and the
total, and charges nothing. Companies the extension would skip are listed in
excludedNodes with the reason. When orderWouldFail is true, nothing can
be extended and the extension order would fail.
You can extend a graph for about 30 days after it completes; after that the extension returns HTTP 410. An order that is still running or did not complete returns HTTP 409.
Share a graph
POST /v2/companies/shareholder-graph/{orderId}/publish publishes a completed
graph and returns a publicUrl to view it and a jsonUrl for its data.
Anyone with these links can open the graph without an API key, so share them
only with the people who need them.
Ultimate beneficial owners
A UBO report lists the people, and sometimes companies, recorded as the company's beneficial owners.
curl -X POST https://api.kausate.com/v2/companies/ubo/sync \
-H "X-API-Key: $API_KEY" \
-H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-d '{"kausateId": "co_de_7aH2IUvdvC6XGzbUbSyhOU"}'The completed order holds result.ultimateBeneficialOwnerReport. Each entry
in ultimateBeneficialOwners has a type (person or company), the person
or company, and its interests. An interest says how the owner holds control:
its type, such as shareholding, votingRights or
otherInfluenceOrControl, a percentage where recorded, and whether it is
direct or indirect.
A UBO report gives the owners as recorded, not a figure derived from the shareholder graph. The two can differ: a graph shows legal ownership through shareholdings, while a beneficial owner can also control a company through voting rights or other means.
Last updated on