Extract Ultimate Beneficial Owners

Return result synchronously with 300s timeout. Not recommended: government registries are unreliable and timeouts are common. Use default async mode with webhooks (recommended) or polling using the orderId instead.

Defaultfalse

batch?boolean

Set to true for bulk, non-interactive requests. They run at lower priority than interactive requests.

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`

curl -X POST "https://api.kausate.com/v2/companies/string/ubo" \  -H "Kausate-Version: 2025-04-01" \  -H "Content-Type: application/json" \  -d '{}'

{
  "orderId": "co_de_4JFFrsbQ99t1nmRw2JgzmG-ubo-org_01ABC-20240319",
  "customerReference": "my-ref-123",
  "status": "completed",
  "requestTime": "2024-03-19T14:30:22.787045Z",
  "responseTime": "2024-03-19T14:32:45.108791Z",
  "result": {
    "ultimateBeneficialOwnerReport": {
      "sources": {
        "de-transparenzregister": {
          "dataSource": "de-transparenzregister",
          "type": "officialRegister",
          "name": "Transparenzregister Deutschland",
          "jurisdictionCode": "de",
          "retrievalTime": "2024-03-19T14:30:50.996406",
          "downloadUrl": "https://example.com/path/to/ubo.pdf",
          "fileHash": "abc123def456...",
          "fileName": "UBO_list_abc123def456.pdf",
          "date": {
            "original": "2024-03-19",
            "normalized": "2024-03-19"
          }
        }
      },
      "ultimateBeneficialOwners": [
        {
          "type": "person",
          "person": {
            "jurisdictionCode": "de",
            "dateOfBirth": {
              "original": "1970-01-01",
              "normalized": "1970-01-01"
            },
            "name": {
              "firstName": "John",
              "lastName": "Doe",
              "fullName": "John Doe"
            },
            "nationalities": [
              {
                "original": "Germany",
                "countryCode": "DE"
              }
            ]
          },
          "interests": [
            {
              "type": "shareholding",
              "percentage": {
                "exact": 25
              },
              "details": "Direct shareholding"
            }
          ],
          "source": "handelsregister_ubo_******"
        }
      ]
    }
  }
}

{
  "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": "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",
        "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"
}

Authorization

api_key

X-API-Key<token>

In: header

Path Parameters

kausateId*string

Company ID

Query Parameters

sync?boolean

Defaultfalse

batch?boolean

Set to true for bulk, non-interactive requests. They run at lower priority than interactive requests.

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.

customerReference?|

metadata?|

Optional customer-supplied JSON metadata echoed back in order responses. Serialized JSON must be at most 4096 bytes.

bypassCache?boolean

If true, bypass daily deduplication and force a fresh request.

Defaultfalse

Response Body

`application/json`

curl -X POST "https://api.kausate.com/v2/companies/string/ubo" \  -H "Kausate-Version: 2025-04-01" \  -H "Content-Type: application/json" \  -d '{}'

{
  "orderId": "co_de_4JFFrsbQ99t1nmRw2JgzmG-ubo-org_01ABC-20240319",
  "customerReference": "my-ref-123",
  "status": "completed",
  "requestTime": "2024-03-19T14:30:22.787045Z",
  "responseTime": "2024-03-19T14:32:45.108791Z",
  "result": {
    "ultimateBeneficialOwnerReport": {
      "sources": {
        "de-transparenzregister": {
          "dataSource": "de-transparenzregister",
          "type": "officialRegister",
          "name": "Transparenzregister Deutschland",
          "jurisdictionCode": "de",
          "retrievalTime": "2024-03-19T14:30:50.996406",
          "downloadUrl": "https://example.com/path/to/ubo.pdf",
          "fileHash": "abc123def456...",
          "fileName": "UBO_list_abc123def456.pdf",
          "date": {
            "original": "2024-03-19",
            "normalized": "2024-03-19"
          }
        }
      },
      "ultimateBeneficialOwners": [
        {
          "type": "person",
          "person": {
            "jurisdictionCode": "de",
            "dateOfBirth": {
              "original": "1970-01-01",
              "normalized": "1970-01-01"
            },
            "name": {
              "firstName": "John",
              "lastName": "Doe",
              "fullName": "John Doe"
            },
            "nationalities": [
              {
                "original": "Germany",
                "countryCode": "DE"
              }
            ]
          },
          "interests": [
            {
              "type": "shareholding",
              "percentage": {
                "exact": 25
              },
              "details": "Direct shareholding"
            }
          ],
          "source": "handelsregister_ubo_******"
        }
      ]
    }
  }
}

{
  "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": "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",
        "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"
}

Extract Ultimate Beneficial Owners

200application/json

400application/json

401application/json

403application/json

404application/json

408application/json

422application/json

429application/json

500application/json

501application/json

502application/json

503application/json

Completed UBO report (via GET /v2/companies/ubo/runs/{orderId})

Initial order response

Extract Ultimate Beneficial Owners

200application/json

400application/json

401application/json

403application/json

404application/json

408application/json

422application/json

429application/json

500application/json

501application/json

502application/json

503application/json

Completed UBO report (via GET /v2/companies/ubo/runs/{orderId})

Initial order response

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`