KausateKausate Docs
Shareholder graph

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.

POST
/v2/companies/shareholder-graph
X-API-Key<token>

Sign up at Kausate.com to get an API key

In: header

Query Parameters

batch?boolean

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.

Defaultfalse

Header Parameters

Kausate-Version?string
Default"2026-08-01"
Formatdate
X-Customer-Id?|

Optional 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