KYB walkthrough
Onboard one sandbox company end to end, from search to a monitor's webhook, with every request and response recorded from the API.
This walkthrough onboards one company the way a KYB check does: find it, read
its company report, its beneficial owners and its shareholder graph, retrieve a
document from the register, and monitor it for changes. Every request and
response below was recorded from the API, in full, on
Sandbox Logistics GmbH (co_zz_4O3wnpE5u1K5AXnkARuhp), a company in
the Kausate sandbox (zz). The ids carry from one step to the next, and the
calls are the same in every jurisdiction.
Before you start
You need an API key whose organization can use the sandbox. Sandbox calls are free. Export the key, and the samples below run as they are:
export KAUSATE_API_KEY="your_api_key"The samples pin the API version they were recorded on with Kausate-Version;
see API versioning. Where a sample fetches a result, a
document or a monitor's events, use the resultUrl, downloadLink or
monitorId your own call returned in place of the recorded one.
Sandbox Logistics GmbH is a living company: its register entry changes once an
hour. Each response shows the company as it stood in the hour it was recorded,
and the webhook at the end reports the change it filed in the following hour.
The order requests
pass "bypassCache": true so that they read the latest change rather than an
order you already placed today.
Find the company
Autocomplete answers while your user types a company name. Each suggestion
carries the kausateId that every other call takes.
curl "https://api.kausate.com/v2/companies/search/autocomplete?query=Sandbox+Logistics&jurisdictionCode=zz" \
-H "X-API-Key: $KAUSATE_API_KEY" \
-H "Kausate-Version: 2026-08-01"{
"results": [
{
"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"jurisdictionCode": "zz",
"name": "Sandbox Logistics GmbH",
"alternativeNames": null,
"identifiers": [
{
"value": "820001",
"type": "zz_sandbox_number",
"source": "zz-sandbox",
"jurisdiction": "zz",
"description": "Kausate Sandbox Number",
"extra": null
}
]
},
{
"kausateId": "co_zz_7KAI2hNYkUCXF7l5HJvJ5M",
"jurisdictionCode": "zz",
"name": "Sandbox Logistics Holding GmbH",
"alternativeNames": null,
"identifiers": [
{
"value": "820002",
"type": "zz_sandbox_number",
"source": "zz-sandbox",
"jurisdiction": "zz",
"description": "Kausate Sandbox Number",
"extra": null
}
]
}
]
}When autocomplete has no match, live search asks the register directly, by name, registration number or the jurisdiction's own search fields.
Prefill a form
Prefill returns the company's core data in one synchronous call: its name, status, legal form, registered address, identifiers and activities. Use it to fill an onboarding form before you order the full report.
curl -X POST "https://api.kausate.com/v2/companies/prefill" \
-H "X-API-Key: $KAUSATE_API_KEY" \
-H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-d '{
"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp"
}'Order the company report
The company report adds the legal representatives and shareholders to the
core data. Ordering it returns an orderId and a resultUrl at once:
curl -X POST "https://api.kausate.com/v2/companies/report" \
-H "X-API-Key: $KAUSATE_API_KEY" \
-H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-d '{
"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"bypassCache": true
}'{
"orderId": "co_zz_4O3wnpE5u1K5AXnkARuhp-report-org_01ABC-20261121130000",
"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"customerReference": null,
"metadata": null,
"customerId": null,
"cachedOrder": false,
"resultUrl": "/v2/companies/report/co_zz_4O3wnpE5u1K5AXnkARuhp-report-org_01ABC-20261121130000"
}Fetch the resultUrl until status is completed, or receive the result by
webhook (see Requests: sync & async):
curl "https://api.kausate.com/v2/companies/report/co_zz_4O3wnpE5u1K5AXnkARuhp-report-org_01ABC-20261121130000" \
-H "X-API-Key: $KAUSATE_API_KEY" \
-H "Kausate-Version: 2026-08-01"Lukas Brandt is the managing director, under relationships.legalRepresentatives.
Sandbox Logistics Holding GmbH holds 90% of the company and Kai Brenner 10%,
under relationships.shareholders. A shareholder that is a company carries its
own kausateId among its identifiers, so you can order its report the same
way. See the company data model for every field.
Identify the beneficial owners
The UBO order returns the natural persons who own or control the company, with the size and kind of their interest.
curl -X POST "https://api.kausate.com/v2/companies/ubo" \
-H "X-API-Key: $KAUSATE_API_KEY" \
-H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-d '{
"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"bypassCache": true
}'{
"orderId": "co_zz_4O3wnpE5u1K5AXnkARuhp-ubo-org_01ABC-20261121130000",
"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"customerReference": null,
"metadata": null,
"customerId": null,
"cachedOrder": false,
"resultUrl": "/v2/companies/ubo/co_zz_4O3wnpE5u1K5AXnkARuhp-ubo-org_01ABC-20261121130000"
}curl "https://api.kausate.com/v2/companies/ubo/co_zz_4O3wnpE5u1K5AXnkARuhp-ubo-org_01ABC-20261121130000" \
-H "X-API-Key: $KAUSATE_API_KEY" \
-H "Kausate-Version: 2026-08-01"{
"orderId": "co_zz_4O3wnpE5u1K5AXnkARuhp-ubo-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": "uboReport",
"ultimateBeneficialOwnerReport": {
"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
}
},
"identifiers": null,
"ultimateBeneficialOwners": [
{
"type": "person",
"person": {
"address": null,
"contact": null,
"jurisdictionCode": "zz",
"dateOfBirth": null,
"gender": null,
"identifiers": null,
"name": {
"firstName": "Henrike",
"lastName": "Vossberg",
"fullName": "Henrike Vossberg"
},
"placeOfBirth": null,
"nationalities": null,
"taxResidencies": null
},
"company": null,
"interests": [
{
"type": "shareholding",
"directOrIndirect": null,
"percentage": {
"exact": 36,
"maximum": null,
"minimum": null,
"exclusiveMinimum": null,
"exclusiveMaximum": null
},
"details": null,
"startDate": null,
"endDate": null
}
],
"source": "zz-sandbox"
}
]
}
},
"error": null,
"code": null,
"currentActivity": null,
"waitingMessage": null,
"cachedOrder": false
}Henrike Vossberg, the largest owner of Sandbox Group SE, owns the company
indirectly through three holding companies, and percentage is her effective
share of it. Kai Brenner's 10% is below the 25% line, so he is a shareholder but
not a beneficial owner. See Ownership for how beneficial owners
are determined.
Map the shareholder graph
The shareholder graph shows the ownership chain behind the beneficial owners: every company and person, and each shareholding between them.
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",
"bypassCache": true
}'{
"orderId": "co_zz_4O3wnpE5u1K5AXnkARuhp-shareholder-graph-depth3-org_01ABC-20261121130000",
"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"customerReference": null,
"metadata": null,
"customerId": null,
"cachedOrder": false,
"resultUrl": "/v2/companies/shareholder-graph/co_zz_4O3wnpE5u1K5AXnkARuhp-shareholder-graph-depth3-org_01ABC-20261121130000"
}curl "https://api.kausate.com/v2/companies/shareholder-graph/co_zz_4O3wnpE5u1K5AXnkARuhp-shareholder-graph-depth3-org_01ABC-20261121130000" \
-H "X-API-Key: $KAUSATE_API_KEY" \
-H "Kausate-Version: 2026-08-01"The graph follows the chain three levels up by default, through Sandbox
Logistics Holding GmbH and Sandbox Beteiligungs GmbH to Sandbox Group SE, and
says so with stopReason: "max_depth_reached". Order it with a larger
maxDepth to reach the people at the top, as the sandbox guide
shows.
Retrieve a document
List the documents the register holds for the company. Each one has a
kausateDocumentId:
curl -X POST "https://api.kausate.com/v2/companies/documents/list" \
-H "X-API-Key: $KAUSATE_API_KEY" \
-H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-d '{
"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp"
}'{
"orderId": "co_zz_4O3wnpE5u1K5AXnkARuhp-list-docs-zz-org_01ABC-20261121130000",
"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"customerReference": null,
"metadata": null,
"customerId": null,
"cachedOrder": false,
"resultUrl": "/v2/companies/documents/list/co_zz_4O3wnpE5u1K5AXnkARuhp-list-docs-zz-org_01ABC-20261121130000"
}curl "https://api.kausate.com/v2/companies/documents/list/co_zz_4O3wnpE5u1K5AXnkARuhp-list-docs-zz-org_01ABC-20261121130000" \
-H "X-API-Key: $KAUSATE_API_KEY" \
-H "Kausate-Version: 2026-08-01"{
"orderId": "co_zz_4O3wnpE5u1K5AXnkARuhp-list-docs-zz-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": "listDocuments",
"documents": [
{
"kausateDocumentId": "doc_zz-sandbox_4dfb09fa18c01b47facd01c6f593bc21",
"title": "Annual Report 2024 — Sandbox Logistics GmbH",
"documentType": "annualReport",
"publicationType": "annualReport",
"publicationDate": "2025-04-30",
"fileType": "pdf",
"source": "zz-sandbox"
},
{
"kausateDocumentId": "doc_zz-sandbox_43554538711a96209820089856358ddf",
"title": "Annual Report 2023 — Sandbox Logistics GmbH",
"documentType": "annualReport",
"publicationType": "annualReport",
"publicationDate": "2024-04-30",
"fileType": "pdf",
"source": "zz-sandbox"
}
],
"totalCount": 2,
"indexedAt": "2026-11-21T13:00:00Z",
"expiresAt": null
},
"error": null,
"code": null,
"currentActivity": null,
"waitingMessage": null,
"cachedOrder": false
}Order one of them, here the 2024 annual report:
curl -X POST "https://api.kausate.com/v2/companies/documents" \
-H "X-API-Key: $KAUSATE_API_KEY" \
-H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-d '{
"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"kausateDocumentId": "doc_zz-sandbox_4dfb09fa18c01b47facd01c6f593bc21",
"bypassCache": true
}'{
"orderId": "co_zz_4O3wnpE5u1K5AXnkARuhp-download-doc_zz-sandbox_4dfb09fa18c01b47facd01c6f593bc21-raw-org_01ABC-20261121130000",
"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"customerReference": null,
"metadata": null,
"customerId": null,
"cachedOrder": false,
"resultUrl": "/v2/companies/documents/co_zz_4O3wnpE5u1K5AXnkARuhp-download-doc_zz-sandbox_4dfb09fa18c01b47facd01c6f593bc21-raw-org_01ABC-20261121130000"
}curl "https://api.kausate.com/v2/companies/documents/co_zz_4O3wnpE5u1K5AXnkARuhp-download-doc_zz-sandbox_4dfb09fa18c01b47facd01c6f593bc21-raw-org_01ABC-20261121130000" \
-H "X-API-Key: $KAUSATE_API_KEY" \
-H "Kausate-Version: 2026-08-01"{
"orderId": "co_zz_4O3wnpE5u1K5AXnkARuhp-download-doc_zz-sandbox_4dfb09fa18c01b47facd01c6f593bc21-raw-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": "document",
"downloadLink": "https://api.kausate.com/documents/example-token/download",
"kausateDocumentId": "doc_zz-sandbox_4dfb09fa18c01b47facd01c6f593bc21",
"documentType": "annualReport",
"expiresAt": null,
"contentType": "application/pdf",
"fileName": "zz_sandbox_820001.pdf"
},
"error": null,
"code": null,
"currentActivity": null,
"waitingMessage": null,
"cachedOrder": false
}The completed order carries a downloadLink. It needs no API key and answers
with a redirect to the file, so keep it private:
curl "https://api.kausate.com/documents/example-token/download" \
--location \
--output document.pdfSee Documents for the kinds of document each register offers, and Document downloads for PDF renditions.
Read the financials (optional)
Where the register publishes annual accounts, the financials order returns them as structured statements, one per financial year.
curl -X POST "https://api.kausate.com/v2/companies/finance" \
-H "X-API-Key: $KAUSATE_API_KEY" \
-H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-d '{
"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"bypassCache": true
}'{
"orderId": "co_zz_4O3wnpE5u1K5AXnkARuhp-financials-org_01ABC-20261121130000",
"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"customerReference": null,
"metadata": null,
"customerId": null,
"cachedOrder": false,
"resultUrl": "/v2/companies/finance/co_zz_4O3wnpE5u1K5AXnkARuhp-financials-org_01ABC-20261121130000"
}curl "https://api.kausate.com/v2/companies/finance/co_zz_4O3wnpE5u1K5AXnkARuhp-financials-org_01ABC-20261121130000" \
-H "X-API-Key: $KAUSATE_API_KEY" \
-H "Kausate-Version: 2026-08-01"See Financials for coverage and the statement fields.
Register a webhook
A webhook receives the result of every asynchronous order and every monitor event for your organization. Register one endpoint:
curl -X POST "https://api.kausate.com/v2/webhooks" \
-H "X-API-Key: $KAUSATE_API_KEY" \
-H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-d '{
"name": "KYB walkthrough",
"url": "https://example.com/kausate/webhooks",
"maxAttempts": 1
}'{
"id": "00000000-0000-4000-8000-000000000001",
"payloadVersion": null,
"name": "KYB walkthrough",
"description": null,
"url": "https://example.com/kausate/webhooks",
"apiVersion": "2026-08-01",
"status": "active",
"maxAttempts": 1,
"orgId": "org_01ABC",
"customerId": null,
"customHeaders": null,
"signingSecret": "kwhsec_fqDdBVNCDiDyGl3JoxQDe/uL7vZ7hRQj4Zqoa8AxDh8=",
"createdAt": "2026-11-21T13:00:00Z",
"updatedAt": "2026-11-21T13:00:00Z"
}Store signingSecret as a secret on the server that receives the webhook. The
secret above is the published example secret from
Receive webhooks; yours is different.
Monitor the company
A monitor checks the company on a schedule and records an event for each
change it finds. This one listens for six event codes and carries your own
metadata into every event:
curl -X POST "https://api.kausate.com/v2/monitors" \
-H "X-API-Key: $KAUSATE_API_KEY" \
-H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-d '{
"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"eventCodesFilter": [
"NAME_CHANGED",
"REGISTERED_ADDRESS_CHANGED",
"ACTIVITIES_CHANGED",
"DIRECTOR_ADDED",
"DIRECTOR_REMOVED",
"SHAREHOLDING_PERCENTAGE_CHANGED"
],
"metadata": {
"caseId": "CASE-12345"
}
}'{
"monitorId": "00000000-0000-4000-8000-000000000002",
"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"companyName": "Sandbox Logistics GmbH",
"categoriesFilter": [
"all"
],
"eventCodesFilter": [
"NAME_CHANGED",
"REGISTERED_ADDRESS_CHANGED",
"ACTIVITIES_CHANGED",
"DIRECTOR_ADDED",
"DIRECTOR_REMOVED",
"SHAREHOLDING_PERCENTAGE_CHANGED"
],
"scheduleCron": "0 0 1 * *",
"metadata": {
"caseId": "CASE-12345"
},
"createdAt": "2026-11-21T13:00:00Z",
"apiUrl": "/v2/monitors/00000000-0000-4000-8000-000000000002"
}A monitor is checked monthly unless you pass a scheduleCron, and changes are
reported from its second check onward. To see a delivery in the sandbox without
waiting a month, pass "scheduleCron": "0 * * * *": the company is then
checked every hour, and each check after the first reports the hour's change.
Receive the change
When a check finds a change, every active webhook receives a signed
monitor.change_detected delivery. The check that followed this monitor's
first one found that the company had moved its registered office, and this is
the request the endpoint received:
POST /kausate/webhooks HTTP/1.1
Content-Type: application/json
Kausate-Version: 2026-08-01
Kausate-Webhook-Id: msg_2Yb7kQx9VdN4
Kausate-Webhook-Timestamp: 1795269600
Kausate-Webhook-Signature: v1,pSvB5M4jHL+Qo0zALK1TqrPDuPGZ/vrQ/yw1DM8cShU=
{"event":"monitor.change_detected","monitor_id":"00000000-0000-4000-8000-000000000002","kausate_id":"co_zz_4O3wnpE5u1K5AXnkARuhp","event_id":"00000000-0000-4000-8000-000000000003","event_code":"REGISTERED_ADDRESS_CHANGED","category":"address","severity":"info","detected_at":"2026-11-21T14:00:00+00:00","before":[{"type":"registered","source":"zz-sandbox","original":"Dradenaustraße 33, 21129 Hamburg, Germany","coordinate":null,"normalized":null,"normalizationMode":"enrich"}],"after":[{"type":"registered","source":"zz-sandbox","original":"Am Sandtorkai 12, 20457 Hamburg, Germany","coordinate":null,"normalized":null,"normalizationMode":"enrich"}],"diff_path":"companyReport.basicInformation.addresses","metadata":{"caseId":"CASE-12345","api_url":"https://api.kausate.com/v2/monitors/00000000-0000-4000-8000-000000000002/events/00000000-0000-4000-8000-000000000003"}}Verify the Kausate-Webhook-Signature header against the exact body before you
trust it. The signingSecret from the previous step verifies this delivery, so
you can test your verifier with it. Receive webhooks has the
verifier in Python and TypeScript, and how to acknowledge, deduplicate and
recover deliveries.
Read the event history
Every event stays on the monitor, with its delivery status, so you can catch up on anything your endpoint missed:
curl "https://api.kausate.com/v2/monitors/00000000-0000-4000-8000-000000000002/events" \
-H "X-API-Key: $KAUSATE_API_KEY" \
-H "Kausate-Version: 2026-08-01"{
"events": [
{
"eventId": "00000000-0000-4000-8000-000000000003",
"monitorId": "00000000-0000-4000-8000-000000000002",
"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"eventCode": "REGISTERED_ADDRESS_CHANGED",
"category": "address",
"severity": "info",
"detectedAt": "2026-11-21T14:00:00Z",
"diffPath": "companyReport.basicInformation.addresses",
"before": [
{
"type": "registered",
"source": "zz-sandbox",
"original": "Dradenaustraße 33, 21129 Hamburg, Germany",
"coordinate": null,
"normalized": null,
"normalizationMode": "enrich"
}
],
"after": [
{
"type": "registered",
"source": "zz-sandbox",
"original": "Am Sandtorkai 12, 20457 Hamburg, Germany",
"coordinate": null,
"normalized": null,
"normalizationMode": "enrich"
}
],
"metadata": {
"caseId": "CASE-12345"
},
"deliveries": [
{
"channel": "webhook",
"status": "delivered",
"target": "https://example.com/kausate/webhooks",
"lastError": null,
"deliveredAt": "2026-11-21T14:00:00Z",
"createdAt": "2026-11-21T14:00:00Z"
}
]
}
],
"total": 1
}See Monitoring for the event codes each country can raise and which of them carry the changed values.
Any failed order carries a code to branch on; see Errors.
Last updated on