Sandbox & testing
A synthetic jurisdiction for testing every operation and your webhook receiver against deterministic mock data
Overview
The Kausate Sandbox is a synthetic jurisdiction, code zz, for building
and testing without calling a real register. It supports every operation
against deterministic mock data, and monitors on its companies deliver a webhook
on every check.
- No setup — no credentials, no IP allow‑listing.
- Free data — search, reports, documents and every other data call on sandbox companies cost no credits.
- Billed monitors — a monitor on a sandbox company is charged like any monitor, at your organization's monitoring price. Sandbox monitors can check as often as hourly, so delete them once your test is done. Data a check fetches for a sandbox company stays free. See Monitoring.
- Deterministic — the same
kausateIdreturns the same data every time, except the living companies described below, which change on purpose. - Opt‑in — enabled per organization. Ask us to turn it on; it does not appear in your jurisdiction list until then.
Sandbox data is fabricated. Use it only to develop and test your integration.
The dataset
Every sandbox company has a kausateId starting with co_zz_. The tables
below list the ones with a known outcome; find any other with autocomplete or
search, as in any other jurisdiction:
curl -H "X-API-Key: $API_KEY" \
-H "Kausate-Version: 2026-08-01" \
"$BASE_URL/v2/companies/search/autocomplete?query=Sandbox&jurisdictionCode=zz"The sandbox is pre‑indexed with ~10,000 companies across six bands:
| Band | Sandbox number | First kausateId | What it's for |
|---|---|---|---|
| Roster | 000001–000005 | co_zz_1a82xPhiHFOOz7CbClDfEI | Curated companies with known outcomes (see below) |
| Bulk | 000006–010005 | co_zz_7I76XR2audazhzblr3TXan | Deterministic generated companies for browsing, search and pagination |
| Living | 700001–700050 | co_zz_6LG5sHkBA6oNdNaMyocX5C | Companies whose data changes over time, for testing monitor events |
| Error | 800001–800005 | co_zz_4eIiedDTNj93xHhsCyieE | Companies that always return a specific error code |
| Shape | 810001–810003 | co_zz_7morpwef7iQ4HAr7ZeM8Q0 | Successes carrying the data shapes integrations break on |
| Ownership | 820001–820005 | co_zz_4O3wnpE5u1K5AXnkARuhp | One group for a full KYB journey: a deep chain, a wide cap table and a living subsidiary |
The five roster companies:
| Sandbox number | kausateId | Company | Status | What it demonstrates |
|---|---|---|---|---|
000001 | co_zz_1a82xPhiHFOOz7CbClDfEI | Sandbox Industries GmbH | Active | Found: a simple company with two individual shareholders, financials and documents |
000002 | co_zz_4DSzHkkecEZyaTh4GNkiWz | Sandbox Holding AG | Active | Ownership: a holding company owned 100% by one individual |
000003 | co_zz_2KGFxpPpQjZtAviMGni9VB | Sandbox Subsidiary Ltd | Active | Ownership: owned 75% by Sandbox Holding AG and 25% by an individual, so a multi‑level shareholder graph and UBO chain |
000004 | co_zz_43oeDt12BJMLkZTcLsB8H0 | Jane Doe Trading | Active | A sole proprietorship: no shareholder block and no financials |
000005 | co_zz_6jqJW6IYIFg5i2ufxYkQ6f | Sandbox Defunct GmbH | In liquidation (insolvent) | Insolvent: in liquidation, inactive, its liquidator as representative |
The kausateId of a sandbox company never changes, so tests can hard‑code it.
To get the kausateId for any other sandbox number, search by number:
curl -H "X-API-Key: $API_KEY" -H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v2/companies/search/sync" \
-d '{"jurisdictionCode": "zz", "advancedQuery": {"sandboxId": "000042"}}'Calling the operations
Every operation works for a sandbox company as it does for a real one. For example, a synchronous company report for Sandbox Industries GmbH:
curl -H "X-API-Key: $API_KEY" -H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v2/companies/report/sync" \
-d '{"kausateId": "co_zz_1a82xPhiHFOOz7CbClDfEI"}'The same id works for finance, shareholder-graph, ubo, documents/list,
documents and prefill. Sandbox Subsidiary Ltd
(co_zz_2KGFxpPpQjZtAviMGni9VB) returns a multi‑level shareholder graph and
UBO chain.
Testing your error handling
Every error carries a stable, dotted code (see Errors).
Each company in the error band always returns one of them:
| Sandbox number | kausateId | Company | Always returns | HTTP | On which calls |
|---|---|---|---|---|---|
800001 | co_zz_4eIiedDTNj93xHhsCyieE | Sandbox Vanished GmbH | company.not_found | 404 | every company call |
800002 | co_zz_3FJjEdV1gdqJ4PqgQnUdIH | Sandbox Never Registered GmbH | company.does_not_exist | 404 | every company call |
800003 | co_zz_3nH2uT5zXs9e23PsKdZ00Y | Sandbox Confidential SAS | company.data_not_diffusable | 422 | every company call |
800004 | co_zz_423EodnKbjbaGy7vLfLnjF | Sandbox Unfiled GmbH | document.not_found | 404 | document retrieval of doc_zz-sandbox_f2f4f61911334c22c44ec0a266e88361 |
800005 | co_zz_1e839anqu3yYcXfk0XJIt3 | Sandbox Restricted GmbH | document.type_unsupported | 400 | document retrieval of doc_zz-sandbox_20261598aa4a634aefb42c7809ca3bba |
"Every company call" means report, financials, UBO, shareholder graph, document list, document retrieval and prefill. The company still appears in search and autocomplete. A report for Sandbox Vanished GmbH returns HTTP 404:
curl -H "X-API-Key: $API_KEY" -H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v2/companies/report/sync" \
-d '{"kausateId": "co_zz_4eIiedDTNj93xHhsCyieE"}' # Sandbox Vanished GmbH{
"detail": "Company not found",
"code": "company.not_found",
"request_id": "req_e14506d86e0e452080d5de23ae5418b5"
}For the two document companies, the report and the document list succeed. The
error comes when you request the kausateDocumentId the table shows, which is
the one that list returns.
The code, message and HTTP status are the same ones a live register failure
produces. All of these are permanent errors, so they return without retrying.
Testing awkward-but-valid data
These companies succeed, with data shapes that real registers produce and integrations often mishandle:
| Sandbox number | kausateId | Company | The shape |
|---|---|---|---|
810001 | co_zz_7morpwef7iQ4HAr7ZeM8Q0 | Sandbox Sparse | Nothing but a name. No status, legal form, address, activity, director, shareholder, document or financial statement |
810002 | co_zz_2VRH96sIsLBT6ChJhkZBqT | Пример Ωμέγα 株式会社 مثال Ünïcøde GmbH | Non‑Latin script in the name, the address and a director's name: Cyrillic, Greek, CJK, Arabic (right‑to‑left) and Latin diacritics |
810003 | co_zz_2xEqRPT2SdGrqmUhMFTzin | Sandbox Vereinigte Maschinenbau- und Anlagenbautechnik Gesellschaft für Präzisionsfertigung, Werkzeugkonstruktion und industrielle Automatisierungssysteme in Norddeutschland und den angrenzenden Küstenregionen Aktiengesellschaft & Compagnie Kommanditgesellschaft auf Aktien mit beschränkter Nachschusspflicht | A legal name over 300 characters, with a matching address and director's name |
For a large result set, search for Acme, Globex, Initech, Umbrella,
Hooli or Cyberdyne. Each matches hundreds of companies in the bulk band:
# autocomplete — returns a full page of 50
curl -H "X-API-Key: $API_KEY" \
-H "Kausate-Version: 2026-08-01" \
"$BASE_URL/v2/companies/search/autocomplete?query=Acme&jurisdictionCode=zz&limit=50"
# search — returns a full page of 20 distinct companies
curl -H "X-API-Key: $API_KEY" -H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v2/companies/search/sync" \
-d '{"jurisdictionCode": "zz", "companyName": "Acme"}'Testing a full KYB journey
The ownership band is one corporate group, built so a single kausateId
carries an onboarding from search to monitoring: a subsidiary with a corporate
parent, an ownership chain five levels deep, a cap table with dozens of owners
at the top, and a register entry that keeps changing.
| Sandbox number | kausateId | Company | What it demonstrates |
|---|---|---|---|
820001 | co_zz_4O3wnpE5u1K5AXnkARuhp | Sandbox Logistics GmbH | Full KYB journey from one id. Living: one register filing per hour — director replaced, office moved, purpose extended, parent raises its stake, renamed. Owned by the holding below, with 5 levels of ownership above it and UBOs through the chain |
820002 | co_zz_7KAI2hNYkUCXF7l5HJvJ5M | Sandbox Logistics Holding GmbH | Corporate parent: holding company owned 100% by the company below |
820003 | co_zz_1z2V9GMYWJAYEjPU6SdZcS | Sandbox Beteiligungs GmbH | Deep chain: an intermediate holding, owned 100% by the group |
820004 | co_zz_3D8DpqsAUbsN3v9kbhiAHS | Sandbox Group SE | Many owners: 33 direct owners with fractional stakes, one of them a company; one founder above the 25% UBO line, the other just below it |
820005 | co_zz_7mX0Fxtl6RsBHwi6xRLs9N | Sandbox Ventures GmbH | The group's corporate investor, owned by two individuals |
Start from Sandbox Logistics GmbH (co_zz_4O3wnpE5u1K5AXnkARuhp) and walk
it like any onboarding: report, documents, financials, then the owners. The
synchronous shareholder graph returns direct shareholders only, and the
asynchronous one stops after three levels unless you ask for more, so order it
with a maxDepth that reaches the people at the top:
curl -H "X-API-Key: $API_KEY" -H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v2/companies/shareholder-graph" \
-d '{"kausateId": "co_zz_4O3wnpE5u1K5AXnkARuhp", "maxDepth": 7}'Then fetch the result with GET /v2/companies/shareholder-graph/{orderId}. At
the default depth the graph ends at Sandbox Group SE with max_depth_reached,
which is a way to test that case too.
The UBO call returns the founder of Sandbox Group SE, whose stake reaches the subsidiary through the whole chain, and, while the parent holds 75%, the subsidiary's minority shareholder.
Sandbox Logistics GmbH is a living company. Each hour its register entry
moves on by one filing, in turn: its registered office moves, its business
purpose is extended (or narrowed again), its managing director is replaced,
its parent raises its stake from 75% to 90% (or back), and it is renamed. When
the parent holds 90%,
the minority shareholder falls below the 25% line and drops out of the UBO
result. Report, shareholder graph and UBO orders placed in the same hour agree
on its owners; search results and the root of the shareholder graph keep the
name the company was first registered under. A repeat order for the same
company the same day can return the stored result, so pass
"bypassCache": true to see the latest filing and test that your onboarding
records pick the change up.
Monitoring → a webhook on every check
Sandbox companies change on every check, so you can test your webhook receiver
deterministically. Register a webhook
for your endpoint (or a webhook.site URL while developing), then create a
monitor for any sandbox company, here the first living company:
curl -H "X-API-Key: $API_KEY" \
-H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v2/monitors" \
-d '{
"kausateId": "co_zz_6LG5sHkBA6oNdNaMyocX5C",
"scheduleCron": "0 * * * *"
}'| Company | What each check delivers |
|---|---|
| Any sandbox company | One OTHER event every check. Use it when you just want a steady webhook stream to test retries and payload shape. |
A living company (700001–700050) | The OTHER event, plus the fields that changed since the last check as realistic events — NAME_CHANGED, COMPANY_STATUS_CHANGED, REGISTERED_ADDRESS_CHANGED, LEGAL_FORM_CHANGED, ACTIVITIES_CHANGED, and director changes. |
Sandbox Logistics GmbH (820001) | The OTHER event, plus one realistic filing per hourly check, in turn — REGISTERED_ADDRESS_CHANGED, ACTIVITIES_CHANGED, DIRECTOR_REMOVED with DIRECTOR_ADDED, SHAREHOLDING_PERCENTAGE_CHANGED, NAME_CHANGED. |
To receive only the steady stream, add "eventCodesFilter": ["OTHER"]. The
event codes a sandbox monitor can receive:
| Event code | Category | Meaning |
|---|---|---|
NAME_CHANGED | other | Legal name changed |
LEGAL_FORM_CHANGED | other | Legal form changed (GmbH → AG, Ltd → PLC) |
REGISTERED_ADDRESS_CHANGED | address | Registered office address changed |
COMPANY_STATUS_CHANGED | status | Status on the register changed |
ACTIVITIES_CHANGED | other | Declared business activities changed |
DIRECTOR_ADDED | legalRepresentatives | Director or officer appointed |
DIRECTOR_REMOVED | legalRepresentatives | Director or officer left |
DIRECTOR_ROLE_CHANGED | legalRepresentatives | An existing director's role changed |
AUTHORIZED_SIGNATORY_CHANGED | legalRepresentatives | Signatory powers changed |
SHAREHOLDER_ADDED | ownership | New shareholder |
SHAREHOLDER_REMOVED | ownership | Shareholder left |
SHAREHOLDING_PERCENTAGE_CHANGED | ownership | An existing shareholder's stake changed |
OTHER | other | Change without a more specific code |
What each of them carries in diff_path, before and after:
| Event code | Raised by | diff_path | before | after |
|---|---|---|---|---|
NAME_CHANGED | Company report | companyReport.basicInformation.legalName | string | string |
LEGAL_FORM_CHANGED | Company report | companyReport.basicInformation.legalForm.normalized | string | string |
REGISTERED_ADDRESS_CHANGED | Company report | companyReport.basicInformation.addresses | Address[] | Address[] |
COMPANY_STATUS_CHANGED | Company report | companyReport.basicInformation.status.normalized | CompanyStatusType | CompanyStatusType |
ACTIVITIES_CHANGED | Company report | companyReport.basicInformation.activities | Activity[] | Activity[] |
DIRECTOR_ADDED | Company report | companyReport.relationships.legalRepresentatives[name=…] | null | LegalRepresentative |
DIRECTOR_REMOVED | Company report | companyReport.relationships.legalRepresentatives[name=…] | LegalRepresentative | null |
DIRECTOR_ROLE_CHANGED | Company report | companyReport.relationships.legalRepresentatives[name=…] | LegalRepresentative | LegalRepresentative |
AUTHORIZED_SIGNATORY_CHANGED | Company report, only when the list cannot be compared entry by entry, which no published company report causes | companyReport.relationships.legalRepresentatives | The whole list | The whole list |
SHAREHOLDER_ADDED | Shareholder graph | graph.nodes[id=…] | null | CompanyNode | PersonNode | RootEntityNode | FreeFloatNode | UnknownNode |
SHAREHOLDER_ADDED | Shareholder graph | graph.edges[id=…] | null | ShareholderEdge |
SHAREHOLDER_REMOVED | Shareholder graph | graph.nodes[id=…] | CompanyNode | PersonNode | RootEntityNode | FreeFloatNode | UnknownNode | null |
SHAREHOLDER_REMOVED | Shareholder graph | graph.edges[id=…] | ShareholderEdge | null |
SHAREHOLDING_PERCENTAGE_CHANGED | Shareholder graph | graph.nodes[id=…] | CompanyNode | PersonNode | RootEntityNode | FreeFloatNode | UnknownNode | CompanyNode | PersonNode | RootEntityNode | FreeFloatNode | UnknownNode |
SHAREHOLDING_PERCENTAGE_CHANGED | Shareholder graph | graph.edges[id=…] | ShareholderEdge | ShareholderEdge |
OTHER | Company report | companyReport.sources.zz-sandbox.retrievalTime | string | string |
scheduleCron is optional and defaults to monthly. Sandbox companies may be
checked as often as hourly — real companies at most once a month — so
0 * * * * is the fastest the sandbox delivers.
From the second check onward, every check delivers
monitor.change_detected webhooks with the changed field in before /
after and the matching event_code. This lets you exercise your receiver's
payload parsing and retry handling without waiting for a real registry change.
See Monitoring for the full webhook payload
shape and delivery semantics.
A sandbox monitor delivers events on every check and keeps retrying
against an unreachable endpoint, so delete the monitor when you're done
testing (DELETE /v2/monitors/{id}).
Last updated on