Sandbox (zz)

Overview

The Kausate Sandbox is a synthetic jurisdiction — code zz — that lets you build and test against Kausate during development without touching a real registry. It implements every Kausate capability against deterministic, in‑process mock data, and its monitoring fires a webhook on every check so you can test your webhook receiver on demand instead of waiting for a real‑world registry change.

• No credentials, no setup — nothing to configure, no IP allow‑listing.
• Free — every sandbox SKU is zero‑credit; sandbox calls never consume credits or money, regardless of your plan.
• Deterministic — the same kausateId returns the same data every time, so your assertions are stable (the one exception is the living companies described below, which evolve on purpose).
• Opt‑in — the sandbox is enabled per organization. Ask us to turn it on for your org; it won't appear in your capability listing until then.

The dataset

All sandbox companies use a kausateId of the form co_zz_…. You can discover them with autocomplete or live search just like any other jurisdiction:

curl -H "X-API-Key: $API_KEY" \
  "$BASE_URL/v2/companies/search/autocomplete?query=Sandbox&jurisdictionCode=zz"

The sandbox is pre‑indexed with ~10,000 companies across three bands:

The five roster companies cover the shapes you'll want to test against:

Every company in these bands is generated deterministically and always returns the same data, so you can hard‑code the kausateIds you discover in your tests without pre‑creating anything. The bands are the whole dataset — a co_zz_… id from outside them isn't a sandbox company and won't resolve.

Exercising the capabilities

Every capability works against a sandbox company exactly as it does for a real jurisdiction. Grab a kausateId from autocomplete, then call any endpoint — for example a synchronous company report:

curl -H "X-API-Key: $API_KEY" -H "Kausate-Version: 2026-05-01" \
  -X POST "$BASE_URL/v2/companies/report/sync" \
  -d '{"kausateId": "co_zz_…"}'

The same id works for search/live, finance, shareholder-graph, ubo, documents/list + documents, and prefill. Use the multi‑level subsidiary (Sandbox Subsidiary Ltd) to see a non‑trivial shareholder graph and UBO chain.

Monitoring → a webhook on every check

The sandbox ships two monitoring sources so you can test your webhook receiver deterministically. Discover them for any sandbox company:

curl -H "X-API-Key: $API_KEY" \
  "$BASE_URL/v2/monitors/sources?kausateId=co_zz_…"

Then create a monitor and point it at your endpoint (or a webhook.site URL while developing). scheduleCron is optional and defaults to monthly; set it explicitly to control how fast the sandbox delivers:

curl -H "X-API-Key: $API_KEY" -H "Kausate-Version: 2026-05-01" \
  -X POST "$BASE_URL/v2/monitors" \
  -d '{
    "kausateId": "co_zz_…",            // a living company for varied events
    "sources": ["zz_sandbox.simulated"],
    "scheduleCron": "*/15 * * * *",    // every 15 min ≈ 96 events/day
    "webhookUrl": "https://your-server.com/webhooks/kausate"
  }'

The first tick records a baseline; every tick after that delivers a monitor.change_detected webhook with the changed field in before / after and the matching event_code. This lets you exercise your receiver's payload parsing, signature verification, and retry handling without waiting for a real registry change. See Monitoring & Webhooks for the full webhook payload shape and delivery semantics.