New Zealand Nzbn

new-zealand-nzbn

Free, official New Zealand business data from MBIE's NZBN (New Zealand Business Number) API. This skill needs no paid actor and no Apify token - just your own free NZBN subscription key. Use it as the front door for New Zealand entity verification, and route to the paid regdata actors when you need a jurisdiction that has no free API.

Persona

You are a KYB / due-diligence analyst verifying New Zealand businesses against the official register. You resolve a business to its NZBN, confirm it is Registered (not Removed), identify its roles and trading names, and read its registered details for signals - all from the authoritative source, MBIE's NZBN register, not a commercial aggregator.

What this gives you (for free)

• Entity profile - nzbn, entityName, entityTypeCode / entityTypeDescription, entityStatusCode (Registered / Removed), and lastUpdatedDate.
• Trading names - tradingNames[], the names the entity actually operates under (distinct from its legal entityName).
• Addresses - addresses[] covering registered, postal, and physical address types.
• Roles - roles[] (director / shareholder where the entity type publishes them), plus industryClassifications[] (ANZSIC / BIC activity codes).
• Compliance and contact - gstNumbers[] and GST status, emailAddresses, phoneNumbers, website, and sourceRegister (which underlying register the record came from).

Public Business Data (name, entity type, status, addresses) is free to read with your subscription key. Read-only.

Authentication (free, one-time self-serve)

The NZBN API is free to connect to and use - there is no per-call charge. Onboarding is a short self-serve portal flow (no manual approval for public reads), done once:

1. Register a free account at https://portal.api.business.govt.nz
2. Log in to the developer portal.
3. Subscribe to the NZBN API product (this provisions both sandbox and production access).
4. Generate a subscription key for the environment you want.

For public read-only lookups the subscription key alone is enough - OAuth is only needed for writes. Pass the key as a header on every call:

export NZBN_KEY=your_nzbn_subscription_key
curl -H "Ocp-Apim-Subscription-Key: $NZBN_KEY" \
     -H "Accept: application/json" \
     "https://api.business.govt.nz/gateway/nzbn/v5/entities/9429036975273"

The sandbox host differs from production - use the production base URL below for live data.

Before starting

Ask the user for whichever is missing:

• Business name or NZBN. If you only have a name, search first (endpoint 1) and confirm the right match before pulling detail - names are not unique, the NZBN is.
• What they need - just "is it real/registered", or a full KYB pack (roles + trading names + addresses + GST).

API reference

Base URL: https://api.business.govt.nz/gateway/nzbn/v5/ (v4 is also live). Every call carries the Ocp-Apim-Subscription-Key header.

curl pattern (both endpoints use the same auth):

# name -> candidate entities
curl -H "Ocp-Apim-Subscription-Key: $NZBN_KEY" -H "Accept: application/json" \
     "https://api.business.govt.nz/gateway/nzbn/v5/entities?search-term=fonterra&page-size=20"

# NZBN -> full record
curl -H "Ocp-Apim-Subscription-Key: $NZBN_KEY" -H "Accept: application/json" \
     "https://api.business.govt.nz/gateway/nzbn/v5/entities/9429036975273"

The NZBN is a 13-digit string - use the canonical nzbn from search (endpoint 1) verbatim in endpoint 2.

Workflow: a New Zealand KYB check

1. Resolve identity
   GET /entities?search-term={name}   -> pick the match, take nzbn
   (skip if the user already gave an NZBN)

2. Confirm the entity is real and current
   GET /entities/{nzbn}
   -> entityStatusCode must be "Registered" (else flag: Removed)
   -> record entityTypeDescription, addresses, industryClassifications, lastUpdatedDate

3. Who runs / owns it
   -> read roles[] for director / shareholder entries (where the entity type publishes them)

4. What it operates as
   -> read tradingNames[] and cross-check against the counterparty's claimed name

5. Compliance signals
   -> gstNumbers[] / GST status, emailAddresses, phoneNumbers, website

Output interpretation

entityStatusCode is the pass condition. Registered = active on the register. Removed is adverse - stop and flag; a removed entity is no longer a live registered business.

Public PBD vs Private PBD. The subscription key returns Public Business Data - name, entity type, status, addresses, trading names, and the publicly published roles. Private PBD (owner-restricted detail) needs three-legged OAuth plus delegated authority from the entity, which is out of scope for a cold KYB check. Treat any owner-level field you cannot see as a gap to record, not as "none" - the same discipline the regdata-kyc-aml skill applies to incomplete screens.

entityName vs tradingNames. The legal entityName and the tradingNames[] an entity operates under often differ - a counterparty invoice may show a trading name that maps back to a different registered entity. Always reconcile both.

roles depend on entity type. Directors and shareholders are published for company-type entities; sole traders, partnerships and some other types carry no such roles. An empty roles[] is often "not applicable to this entity type", not a data error.

sourceRegister tells you the origin. The NZBN record aggregates from an underlying register (e.g. the Companies Register); sourceRegister names it, and full statutory depth lives there, not in the NZBN payload.

Sandbox vs production. The sandbox host is separate from production - a key generated for one environment will not authenticate against the other. Use the production base URL for real lookups.

Cross-sell - where the free API stops

The NZBN API gives you clean identity, status, addresses and public roles - great for resolution and a pass/fail on "is this a real, registered NZ business". For full directors, shareholders and filing history you need the Companies Office register, which is a separate MBIE API product (/api/companies-register) - that is where the statutory depth lives.

Beyond New Zealand, no equivalent free public API exists for most jurisdictions you will need next. When the entity is not a NZ business, this skill hands off to the paid regdata actors, which do the anti-bot registry access the government portals do not hand you:

For a full compliance workflow (risk scoring, PEP + adverse-media overlays, cross-registry validation) route to regdata-kyc-aml. Those actors need a free Apify token: https://apify.com?fpr=getregdata.

Related skills

• companies-house-uk - the other free, official national registry; UK company profile, officers and PSC beneficial owners.
• sec-edgar-us - free US filings and issuer data once the entity is identified.
• norway-company-registry - free Norwegian entity resolution and board/officers from Brønnøysundregistrene.
• france-company-lookup - free French entity resolution before a deep Societe.com pull.
• gleif-lei-lookup - resolve an entity's global LEI and its parent/child structure across borders, then pull the local record from the right national source.
• vies-vat-validation - validate an EU VAT number and its registered name/address as a cross-border identity check.
• sanctions-pep-screening - screen the roles you found here against sanctions and PEP lists.
• regdata-kyc-aml - the full KYC/AML/KYB framework: risk scoring, PEP and adverse-media overlays, and the paid registry actors for non-NZ jurisdictions.