KausateKausate Docs
Company Data
Viewing API version 2026-05-01. View the latest version.

Extract Shareholder Graph (sync)

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. Requests with `maxDepth>1` are rejected with 400; use the async `POST /v2/companies/shareholder-graph` endpoint for multi-level extraction.

The async POST /v2/companies/shareholder-graph endpoint is the preferred method. Government registries frequently time out — async with webhooks or polling handles those failures gracefully.

POST
/v2/companies/shareholder-graph/sync

Authorization

api_key
X-API-Key<token>

Sign up at Kausate.com to get an API key

In: header

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"2026-05-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

application/json

curl -X POST "https://api.kausate.com/v2/companies/shareholder-graph/sync" \  -H "Kausate-Version: 2026-05-01" \  -H "Content-Type: application/json" \  -d '{    "kausateId": "string"  }'
{
  "orderId": "string",
  "kausateId": "string",
  "companyName": "string",
  "customerReference": "string",
  "metadata": {},
  "customerId": "string",
  "status": "running",
  "requestTime": "2019-08-24T14:15:22Z",
  "responseTime": "2019-08-24T14:15:22Z",
  "result": {
    "type": "shareholderGraph",
    "graph": {
      "nodes": [
        {
          "id": "string",
          "type": "company",
          "data": {
            "kausateId": "string",
            "legalName": "string",
            "jurisdictionCode": "ec",
            "identifiers": [
              {
                "value": "string",
                "type": "ad_commercial_register_number",
                "source": "string",
                "description": "string",
                "extra": {}
              }
            ],
            "cumulativeOwnership": {
              "exact": 100,
              "maximum": 100,
              "minimum": 100,
              "exclusiveMinimum": 100,
              "exclusiveMaximum": 100
            },
            "status": {
              "original": "string",
              "normalized": "active",
              "isActive": true
            },
            "sourceIds": [
              "string"
            ]
          }
        }
      ],
      "edges": [
        {
          "id": "string",
          "source": "string",
          "target": "string",
          "data": {
            "interestType": "shareholding",
            "interestDetails": "string",
            "role": {
              "original": "string",
              "englishTranslation": "string",
              "originalLanguage": "string",
              "iso5009RoleCode": "string",
              "normalized": "Director"
            },
            "percentage": {
              "exact": 100,
              "maximum": 100,
              "minimum": 100,
              "exclusiveMinimum": 100,
              "exclusiveMaximum": 100
            },
            "shareClass": "string",
            "numberOfShares": 0,
            "totalNominalValue": {
              "amount": "string",
              "iso4217CurrencyCode": "string"
            },
            "sourceId": "string"
          }
        }
      ],
      "rootCompanyId": "string",
      "maxDepth": 0,
      "extractionTimestamp": "string",
      "sources": {
        "property1": {
          "type": "selfDeclaration",
          "name": "string",
          "jurisdictionCode": "ec",
          "retrievalTime": "string",
          "downloadUrl": "string",
          "fileHash": "string",
          "fileName": "string",
          "date": {
            "original": "string",
            "normalized": "string"
          }
        },
        "property2": {
          "type": "selfDeclaration",
          "name": "string",
          "jurisdictionCode": "ec",
          "retrievalTime": "string",
          "downloadUrl": "string",
          "fileHash": "string",
          "fileName": "string",
          "date": {
            "original": "string",
            "normalized": "string"
          }
        }
      },
      "stopReason": "completed",
      "stopReasonDetail": "string",
      "errors": [
        {
          "path": "string",
          "code": "string",
          "detail": "string"
        }
      ]
    }
  },
  "error": "string",
  "code": "string",
  "currentActivity": "string",
  "cachedOrder": false
}
{
  "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": "The order did not complete within the timeout. Retry asynchronously and poll for the result.",
  "code": "request.timeout",
  "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