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 other co_zz_… id you ask for is generated deterministically on demand, so you can hard‑code ids in tests without pre‑creating anything.

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_…"

Create a monitor with a one‑minute cron and point it at your endpoint (or a webhook.site URL while developing):

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": "* * * * *",
    "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.