KausateKausate Docs
Company Data
Viewing API version 2025-04-01. View the latest version.

Extract Shareholder Graph

Extract multi-level shareholder graph for a company.

POST
/v2/companies/{kausateId}/shareholder-graph

Authorization

api_key
X-API-Key<token>

Sign up at Kausate.com to get an API key

In: header

Path Parameters

kausateId*string

Company ID

Query Parameters

batch?boolean

Mark as a batch/backfill request. Batch requests run at lowest priority to avoid blocking interactive queries.

Defaultfalse

Header Parameters

Kausate-Version?string
Default"2025-04-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/string/shareholder-graph" \  -H "Kausate-Version: 2025-04-01" \  -H "Content-Type: application/json" \  -d '{}'

{
  "orderId": "shareholder-graph-co_de_4JFFrsbQ99t1nmRw2JgzmG-20240319143022",
  "customerReference": "my-ref-123",
  "status": "completed",
  "requestTime": "2024-03-19T14:30:22.787045Z",
  "responseTime": "2024-03-19T14:35:45.108791Z",
  "result": {
    "type": "shareholderGraph",
    "graph": {
      "nodes": [
        {
          "id": "co_de_4JFFrsbQ99t1nmRw2JgzmG",
          "type": "rootEntity",
          "data": {
            "kausateId": "co_de_4JFFrsbQ99t1nmRw2JgzmG",
            "legalName": "Parent Company GmbH",
            "jurisdictionCode": "de",
            "identifiers": [
              {
                "value": "co_de_4JFFrsbQ99t1nmRw2JgzmG",
                "type": "kausate_id",
                "description": "Kausate universal company identifier",
                "source": "aa-kausate",
                "jurisdiction": "aa"
              },
              {
                "value": "4JFFrsbQ99t1nmRw2JgzmG",
                "type": "de_registernumber_full",
                "description": "German commercial register number with court code",
                "source": "de-handelsregister",
                "jurisdiction": "de"
              }
            ],
            "cumulativeOwnership": {
              "exact": 100
            },
            "shareholderReport": {
              "sources": {
                "de-handelsregister": {
                  "dataSource": "de-handelsregister",
                  "type": "officialRegister",
                  "name": "Handelsregister Deutschland",
                  "jurisdictionCode": "de",
                  "retrievalTime": "2024-03-19T14:30:00Z",
                  "downloadUrl": "https://www.kausate.com/downloads/sample.pdf",
                  "fileHash": "abc123...",
                  "fileName": "sample.pdf",
                  "date": {
                    "original": "2024-03-15",
                    "normalized": "2024-03-15"
                  }
                }
              },
              "shareholders": [
                {
                  "type": "company",
                  "company": {
                    "name": "Subsidiary AG",
                    "jurisdictionCode": "de",
                    "identifiers": [
                      {
                        "value": "HRB 98765",
                        "type": "de_registernumber_weak",
                        "description": "AG Frankfurt",
                        "source": "de-handelsregister",
                        "jurisdiction": "de"
                      },
                      {
                        "value": "co_de_5KGGtcdR00u2onSx3KhAnH",
                        "type": "kausate_id",
                        "description": "Kausate Universal Identifier",
                        "source": "aa-kausate",
                        "jurisdiction": "aa"
                      }
                    ]
                  },
                  "numberOfShares": 750,
                  "percentage": {
                    "exact": 75
                  },
                  "totalNominalValue": {
                    "amount": "75000",
                    "iso4217CurrencyCode": "EUR"
                  },
                  "interestType": "SHAREHOLDING",
                  "source": "handelsregister_shareholder_abc123"
                },
                {
                  "type": "person",
                  "person": {
                    "jurisdictionCode": "de",
                    "name": {
                      "firstName": "John",
                      "lastName": "Doe",
                      "fullName": "John Doe"
                    }
                  },
                  "numberOfShares": 250,
                  "percentage": {
                    "exact": 25
                  },
                  "totalNominalValue": {
                    "amount": "25000",
                    "iso4217CurrencyCode": "EUR"
                  },
                  "interestType": "SHAREHOLDING",
                  "source": "handelsregister_shareholder_abc123"
                }
              ]
            }
          }
        },
        {
          "id": "co_de_5KGGtcdR00u2onSx3KhAnH",
          "type": "company",
          "data": {
            "kausateId": "co_de_5KGGtcdR00u2onSx3KhAnH",
            "legalName": "Subsidiary AG",
            "jurisdictionCode": "de",
            "identifiers": [
              {
                "value": "co_de_5KGGtcdR00u2onSx3KhAnH",
                "type": "kausate_id",
                "description": "Kausate universal company identifier",
                "source": "aa-kausate",
                "jurisdiction": "aa"
              },
              {
                "value": "HRB 98765",
                "type": "de_registernumber_weak",
                "description": "German commercial register number",
                "source": "de-handelsregister",
                "jurisdiction": "de"
              }
            ],
            "cumulativeOwnership": {
              "exact": 75
            }
          }
        },
        {
          "id": "person_John_Doe",
          "type": "person",
          "data": {
            "name": "John Doe",
            "cumulativeOwnership": {
              "exact": 25
            }
          }
        }
      ],
      "edges": [
        {
          "id": "co_de_4JFFrsbQ99t1nmRw2JgzmG-co_de_5KGGtcdR00u2onSx3KhAnH",
          "source": "co_de_4JFFrsbQ99t1nmRw2JgzmG",
          "target": "co_de_5KGGtcdR00u2onSx3KhAnH",
          "data": {
            "interestType": "SHAREHOLDING",
            "percentage": {
              "exact": 75
            },
            "numberOfShares": 750,
            "totalNominalValue": {
              "amount": "75000",
              "iso4217CurrencyCode": "EUR"
            }
          }
        },
        {
          "id": "co_de_4JFFrsbQ99t1nmRw2JgzmG-person_John_Doe",
          "source": "co_de_4JFFrsbQ99t1nmRw2JgzmG",
          "target": "person_John_Doe",
          "data": {
            "interestType": "SHAREHOLDING",
            "percentage": {
              "exact": 25
            },
            "numberOfShares": 250,
            "totalNominalValue": {
              "amount": "25000",
              "iso4217CurrencyCode": "EUR"
            }
          }
        }
      ],
      "rootCompanyId": "co_de_4JFFrsbQ99t1nmRw2JgzmG",
      "maxDepth": 3,
      "extractionTimestamp": "2024-03-19T14:30:22Z"
    }
  }
}

{
  "detail": "Invalid company ID format",
  "code": "request.invalid",
  "request_id": "req_01J8Z5V4Q2X9N7B3C6D1E0F2G4"
}
{
  "detail": "Not authenticated",
  "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",
        "jurisdictionCode"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "code": "request.invalid",
  "request_id": "req_01J8Z5V4Q2X9N7B3C6D1E0F2G4"
}
{
  "detail": "Rate limit exceeded, please try again later",
  "code": "source.rate_limited",
  "request_id": "req_01J8Z5V4Q2X9N7B3C6D1E0F2G4"
}
{
  "detail": "An internal error occurred",
  "code": "internal.unexpected",
  "request_id": "req_01J8Z5V4Q2X9N7B3C6D1E0F2G4"
}
{
  "detail": "This capability is not available for this jurisdiction",
  "code": "capability.not_available",
  "request_id": "req_01J8Z5V4Q2X9N7B3C6D1E0F2G4"
}
{
  "detail": "Network connection error",
  "code": "source.network_error",
  "request_id": "req_01J8Z5V4Q2X9N7B3C6D1E0F2G4"
}
{
  "detail": "Data source temporarily unavailable",
  "code": "source.unavailable",
  "request_id": "req_01J8Z5V4Q2X9N7B3C6D1E0F2G4"
}

Last updated on

Retrieve Company ReportPOST

Retrieve a structured company report from official registries.

Publish Shareholder GraphPOST

Publish a completed shareholder-graph order behind an unguessable public URL. The returned `publicUrl` renders the same UBO studio visualization as the authenticated app. The slug is a capability token — anyone holding it can view the graph, so treat it like a secret.