Shareholder graph: order (async)
Place an order for a multi-level shareholder graph. Poll GET /v2/companies/shareholder-graph/{orderId} or subscribe via webhook.
When to use it
Order a shareholder graph to follow ownership upward from one company: the
owners of each corporate shareholder are added level by level, until natural
persons are reached or maxDepth (default 3) stops the walk. Use it for
ownership structures and indirect holdings. When you only need the resulting
beneficial owners, order them
directly as a flat list.
A graph can take minutes. Receive it by webhook, or poll resultUrl.
Example
Sandbox Logistics GmbH is owned by Sandbox Logistics Holding GmbH and one person. Above the holding sit Sandbox Beteiligungs GmbH and Sandbox Group SE, which has 33 owners.
curl -X POST https://api.kausate.com/v2/companies/shareholder-graph \
-H "X-API-Key: your_api_key" \
-H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-d '{"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp"}'The completed order
(GET resultUrl):
{
"orderId": "co_zz_4O3wnpE5u1K5AXnkARuhp-shareholder-graph-depth3-org_01ABC-20261121130000",
"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"companyName": "Sandbox Logistics GmbH",
"customerReference": null,
"metadata": null,
"customerId": null,
"status": "completed",
"requestTime": "2026-11-21T13:00:00Z",
"responseTime": "2026-11-21T13:00:00Z",
"result": {
"type": "shareholderGraph",
"graph": {
"nodes": [
{
"id": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"type": "rootEntity",
"data": {
"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"legalName": "Sandbox Logistics GmbH",
"jurisdictionCode": "zz",
"identifiers": [
{
"value": "820001",
"type": "zz_sandbox_number",
"source": "zz-sandbox",
"jurisdiction": "zz",
"description": "Kausate Sandbox Number",
"extra": null
}
],
"cumulativeOwnership": {
"exact": 0,
"maximum": null,
"minimum": null,
"exclusiveMinimum": null,
"exclusiveMaximum": null
},
"jointlyHeldOwnership": null,
"status": {
"original": "Active",
"normalized": "active",
"isActive": true
},
"sourceIds": [
"zz-sandbox"
],
"risk": null
}
},
{
"id": "co_zz_7KAI2hNYkUCXF7l5HJvJ5M",
"type": "company",
"data": {
"kausateId": "co_zz_7KAI2hNYkUCXF7l5HJvJ5M",
"legalName": "Sandbox Logistics Holding GmbH",
"jurisdictionCode": "zz",
"identifiers": [
{
"value": "co_zz_7KAI2hNYkUCXF7l5HJvJ5M",
"type": "kausate_id",
"source": "zz-sandbox",
"jurisdiction": "zz",
"description": null,
"extra": null
},
{
"value": "820002",
"type": "zz_sandbox_number",
"source": "zz-sandbox",
"jurisdiction": "zz",
"description": null,
"extra": null
}
],
"cumulativeOwnership": {
"exact": 90,
"maximum": null,
"minimum": null,
"exclusiveMinimum": null,
"exclusiveMaximum": null
},
"jointlyHeldOwnership": null,
"status": {
"original": "Active",
"normalized": "active",
"isActive": true
},
"sourceIds": [
"zz-sandbox_00000001"
],
"risk": null
}
},
{
"id": "person_brenner_kai",
"type": "person",
"data": {
"name": "Kai Brenner",
"role": null,
"dateOfBirth": null,
"address": null,
"nationalities": null,
"gender": null,
"contact": null,
"jurisdictionCode": "zz",
"identifiers": null,
"cumulativeOwnership": {
"exact": 10,
"maximum": null,
"minimum": null,
"exclusiveMinimum": null,
"exclusiveMaximum": null
},
"jointlyHeldOwnership": null,
"indirectOwnership": null,
"sourceIds": [
"zz-sandbox"
],
"risk": null
}
},
{
"id": "co_zz_1z2V9GMYWJAYEjPU6SdZcS",
"type": "company",
"data": {
"kausateId": "co_zz_1z2V9GMYWJAYEjPU6SdZcS",
"legalName": "Sandbox Beteiligungs GmbH",
"jurisdictionCode": "zz",
"identifiers": [
{
"value": "co_zz_1z2V9GMYWJAYEjPU6SdZcS",
"type": "kausate_id",
"source": "zz-sandbox",
"jurisdiction": "zz",
"description": null,
"extra": null
},
{
"value": "820003",
"type": "zz_sandbox_number",
"source": "zz-sandbox",
"jurisdiction": "zz",
"description": null,
"extra": null
}
],
"cumulativeOwnership": {
"exact": 90,
"maximum": null,
"minimum": null,
"exclusiveMinimum": null,
"exclusiveMaximum": null
},
"jointlyHeldOwnership": null,
"status": {
"original": "Active",
"normalized": "active",
"isActive": true
},
"sourceIds": [
"zz-sandbox_00000002"
],
"risk": null
}
},
{
"id": "co_zz_3D8DpqsAUbsN3v9kbhiAHS",
"type": "company",
"data": {
"kausateId": "co_zz_3D8DpqsAUbsN3v9kbhiAHS",
"legalName": "Sandbox Group SE",
"jurisdictionCode": "zz",
"identifiers": [
{
"value": "co_zz_3D8DpqsAUbsN3v9kbhiAHS",
"type": "kausate_id",
"source": "zz-sandbox",
"jurisdiction": "zz",
"description": null,
"extra": null
},
{
"value": "820004",
"type": "zz_sandbox_number",
"source": "zz-sandbox",
"jurisdiction": "zz",
"description": null,
"extra": null
}
],
"cumulativeOwnership": {
"exact": 90,
"maximum": null,
"minimum": null,
"exclusiveMinimum": null,
"exclusiveMaximum": null
},
"jointlyHeldOwnership": null,
"status": null,
"sourceIds": [
"zz-sandbox"
],
"risk": null
}
}
],
"edges": [
{
"id": "co_zz_4O3wnpE5u1K5AXnkARuhp-co_zz_7KAI2hNYkUCXF7l5HJvJ5M",
"source": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"target": "co_zz_7KAI2hNYkUCXF7l5HJvJ5M",
"data": {
"interestType": "shareholding",
"interestDetails": null,
"directOrIndirect": null,
"beneficialOwnershipOrControl": null,
"startDate": null,
"endDate": null,
"status": null,
"role": null,
"percentage": {
"exact": 90,
"maximum": null,
"minimum": null,
"exclusiveMinimum": null,
"exclusiveMaximum": null
},
"shareClass": null,
"numberOfShares": null,
"totalNominalValue": null,
"jointHolding": null,
"sourceId": "zz-sandbox",
"risk": null
}
},
{
"id": "co_zz_4O3wnpE5u1K5AXnkARuhp-person_brenner_kai",
"source": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"target": "person_brenner_kai",
"data": {
"interestType": "shareholding",
"interestDetails": null,
"directOrIndirect": null,
"beneficialOwnershipOrControl": null,
"startDate": null,
"endDate": null,
"status": null,
"role": null,
"percentage": {
"exact": 10,
"maximum": null,
"minimum": null,
"exclusiveMinimum": null,
"exclusiveMaximum": null
},
"shareClass": null,
"numberOfShares": null,
"totalNominalValue": null,
"jointHolding": null,
"sourceId": "zz-sandbox",
"risk": null
}
},
{
"id": "co_zz_7KAI2hNYkUCXF7l5HJvJ5M-co_zz_1z2V9GMYWJAYEjPU6SdZcS",
"source": "co_zz_7KAI2hNYkUCXF7l5HJvJ5M",
"target": "co_zz_1z2V9GMYWJAYEjPU6SdZcS",
"data": {
"interestType": "shareholding",
"interestDetails": null,
"directOrIndirect": null,
"beneficialOwnershipOrControl": null,
"startDate": null,
"endDate": null,
"status": null,
"role": null,
"percentage": {
"exact": 100,
"maximum": null,
"minimum": null,
"exclusiveMinimum": null,
"exclusiveMaximum": null
},
"shareClass": null,
"numberOfShares": null,
"totalNominalValue": null,
"jointHolding": null,
"sourceId": "zz-sandbox_00000001",
"risk": null
}
},
{
"id": "co_zz_1z2V9GMYWJAYEjPU6SdZcS-co_zz_3D8DpqsAUbsN3v9kbhiAHS",
"source": "co_zz_1z2V9GMYWJAYEjPU6SdZcS",
"target": "co_zz_3D8DpqsAUbsN3v9kbhiAHS",
"data": {
"interestType": "shareholding",
"interestDetails": null,
"directOrIndirect": null,
"beneficialOwnershipOrControl": null,
"startDate": null,
"endDate": null,
"status": null,
"role": null,
"percentage": {
"exact": 100,
"maximum": null,
"minimum": null,
"exclusiveMinimum": null,
"exclusiveMaximum": null
},
"shareClass": null,
"numberOfShares": null,
"totalNominalValue": null,
"jointHolding": null,
"sourceId": "zz-sandbox_00000002",
"risk": null
}
}
],
"rootCompanyId": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"maxDepth": 3,
"extractionTimestamp": "2026-11-21T13:00:00+00:00",
"sources": {
"zz-sandbox": {
"dataSource": "zz-sandbox",
"type": "primaryResearch",
"name": "Kausate Sandbox",
"jurisdictionCode": "zz",
"retrievalTime": "2026-11-21T13:00:00+00:00",
"downloadUrl": null,
"fileHash": null,
"fileName": null,
"date": null
},
"zz-sandbox_00000001": {
"dataSource": "zz-sandbox",
"type": "primaryResearch",
"name": "Kausate Sandbox",
"jurisdictionCode": "zz",
"retrievalTime": "2026-11-21T13:00:00+00:00",
"downloadUrl": null,
"fileHash": null,
"fileName": null,
"date": null
},
"zz-sandbox_00000002": {
"dataSource": "zz-sandbox",
"type": "primaryResearch",
"name": "Kausate Sandbox",
"jurisdictionCode": "zz",
"retrievalTime": "2026-11-21T13:00:00+00:00",
"downloadUrl": null,
"fileHash": null,
"fileName": null,
"date": null
}
},
"stopReason": "max_depth_reached",
"stopReasonDetail": "1 company node(s) at max depth 3 were not expanded: Sandbox Group SE (co_zz_3D8DpqsAUbsN3v9kbhiAHS). Increase the requested depth or extend this graph to continue.",
"errors": []
}
},
"error": null,
"code": null,
"currentActivity": null,
"waitingMessage": null,
"cachedOrder": false
}An edge points from the owned company (source) to its owner (target) and
carries the direct holding; cumulativeOwnership on a node is its effective
share of the root company. With the default maxDepth of 3 the walk stops at
Sandbox Group SE: stopReason is max_depth_reached, and stopReasonDetail
names the company not yet expanded. The graph returned so far is still valid
and can be extended.
Related guides
- Requests: sync & async: time budgets for long graphs
- Sandbox: the multi-level ownership companies used here
Authorization
api_key Sign up at Kausate.com to get an API key
In: header
Query Parameters
Set to true for batch orders: many orders you submit together and do not need answered immediately. They run at a lower priority than interactive orders.
falseHeader Parameters
"2026-08-01"dateOptional customer ID
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.kausate.com/v2/companies/shareholder-graph" \ -H "X-API-Key: $KAUSATE_API_KEY" \ -H "Kausate-Version: 2026-08-01" \ -H "Content-Type: application/json" \ -d '{ "kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp"}'{
"orderId": "string",
"kausateId": "string",
"customerReference": "string",
"metadata": {},
"customerId": "string",
"cachedOrder": true,
"resultUrl": "string"
}{
"detail": "Invalid company ID format",
"code": "request.invalid",
"request_id": "req_01J8Z5V4Q2X9N7B3C6D1E0F2G4"
}{
"detail": "API key is required",
"code": "auth.unauthorized",
"request_id": "req_01J8Z5V4Q2X9N7B3C6D1E0F2G4"
}{
"detail": "Invalid API key",
"code": "auth.forbidden",
"request_id": "req_01J8Z5V4Q2X9N7B3C6D1E0F2G4"
}{
"detail": "Company not found",
"code": "company.not_found",
"request_id": "req_01J8Z5V4Q2X9N7B3C6D1E0F2G4"
}{
"detail": [
{
"loc": [
"body",
"kausateId"
],
"msg": "Field required",
"type": "missing"
}
],
"code": "request.invalid",
"request_id": "req_01J8Z5V4Q2X9N7B3C6D1E0F2G4"
}{
"detail": "The data source is rate-limiting requests right now, please try again later",
"code": "source.rate_limited",
"request_id": "req_01J8Z5V4Q2X9N7B3C6D1E0F2G4"
}{
"detail": "An unexpected error occurred. If this persists, please contact support@kausate.com",
"code": "internal.unexpected",
"request_id": "req_01J8Z5V4Q2X9N7B3C6D1E0F2G4"
}{
"detail": "This capability is offered for the requested jurisdiction but is not usable right now because of a fault on our side. Please contact support@kausate.com",
"code": "capability.not_available",
"request_id": "req_01J8Z5V4Q2X9N7B3C6D1E0F2G4"
}{
"detail": "Network error while reaching the data source",
"code": "source.network_error",
"request_id": "req_01J8Z5V4Q2X9N7B3C6D1E0F2G4"
}{
"detail": "Data source temporarily unavailable",
"code": "source.unavailable",
"request_id": "req_01J8Z5V4Q2X9N7B3C6D1E0F2G4"
}Last updated on
Order statusGET
Get the status of a company report order and, once complete, its result.
SyncPOST
Extract a shareholder graph synchronously. Blocks for up to 300 seconds. Only `maxDepth=1` is supported for sync requests — deeper graphs exceed the 300s budget. Omitting `maxDepth` means 1 here; requests with `maxDepth>1` are rejected with 400; use the async `POST /v2/companies/shareholder-graph` endpoint for multi-level extraction.