assembl · agent tool

nz-who-runs-it

One job: given a New Zealand company name or NZBN, return structured public ownership/control hints — legal name, NZBN, directors when published, registered office when published, contact hints, and source links. Wraps NZBN + Companies Office gateways (same adapters as mcp-nzbn / mcp-companies-office).

Use when

You need to know who publicly runs an NZ company before outreach or diligence.
You have a trading name and need the NZBN + legal name.
You have an NZBN and need directors / registered office if published.

Do not use for credit checks, AML conclusions, or non-public filings. Do not invent contacts. Foodstuffs / supermarket APIs are out of scope.

Endpoint

POST /api/tools/nz-who-runs-it
GET  /api/tools/nz-who-runs-it   # health + docs pointer
Auth: Authorization: Bearer <key>
   or X-Assembl-Tool-Key: <key>

Input / output

// request
{ "company": "assembl" | "9429053514950" }

// response.data
{
  "status": "ok" | "partial" | "not_found",
  "legalName": string | null,
  "nzbn": string | null,
  "companyNumber": string | null,
  "directors": [{ "name", "role?", "appointedOn?" }],
  "registeredOffice": string | null,
  "contactHints": { "emails", "phones", "websites", "notes" },
  "adapters": { "nzbn", "companiesOffice" },
  "privacy": { "directorsArePersonalInformation", "notice", "doNot", "sources" },
  "sourceLinks": [{ "label", "url" }],
  "sandbox": boolean,
  "gaps": string[]
}

Sandbox (test_ keys)

Any key starting with test_ stays in sandbox — realistic fixtures only, never live registers. Demo key: test_assembl_demo_nz_who_runs_it. Try assembl, 9429053514950, trade me.

curl -sS -X POST "$ORIGIN/api/tools/nz-who-runs-it" \
  -H "Authorization: Bearer test_assembl_demo_nz_who_runs_it" \
  -H "Content-Type: application/json" \
  -d '{"company":"assembl"}'

Live data + env

Free subscription keys at api.business.govt.nz. Live requires NZBN_API_KEY (legacy NZBN_API_TOKEN). Optional COMPANIES_OFFICE_API_KEY enriches directors. Missing NZBN key → 503 with a fix hint — never fake live data. Use test_ keys when either key is unset.

Privacy Act (directors)

Director names are personal information even when published. This tool redistributes only public-register name / role / appointment fields, cites NZBN + Companies Office on every response, and never returns residential addresses or dates of birth. Callers must not build secondary director dossiers (IPP 1, 9, 11). Receipts store director counts, not names.

Errors / cap / receipts

401 missing/invalid key — send Bearer or X-Assembl-Tool-Key.
400 validation — body needs non-empty company.
429 daily cap — default sandbox 100¢/day UTC; unit cost 1¢.
503 upstream unconfigured — set NZBN_API_KEY or use test_.
Receipts: GET /api/tools/keys/{keyId}/receipts or ?format=json.

assembl · health JSON · next: nz-trade-finder · meeting-enhance · nz-compliance-ping (register-only)