NZBN Integration

Category: API & Integration Section: Articles Last Updated: 2023-11-01

---

Search and retrieve New Zealand company information directly within your forms using the NZBN (New Zealand Business Number) integration.

---

Overview

The NZBN component connects to the New Zealand Government's business API, allowing users to search for registered companies and auto-populate form fields with company data.

---

Adding the NZBN Component

1. Open your form in the Form Builder
2. Navigate to Common Fields in the component menu
3. Drag the NZBN component onto your form

---

How It Works

When users search for a company:

1. The component queries the NZ business register
2. Matching companies are displayed for selection
3. Company data is captured in the field's JSON object

TIP

Unlike other composite fields, the NZBN component doesn't display company details directly. This gives form designers full control over which data to show.

---

Available Data Fields

For an NZBN component named nzbnSearch, the following properties are available:

Property	Description
nzbnSearch.EntityName	Company name
nzbnSearch.SearchText	User's search query
nzbnSearch.entityStatusDescription	Registration status
nzbnSearch.entityTypeDescription	Entity type (e.g., Limited Company)
nzbnSearch.nzbn	New Zealand Business Number

---

Accessing Extended Data

Additional company details are available in nzbnSearch.entity as a JSON string. Use JavaScript to parse and extract specific fields:

// Parse the entity data
var entityData = JSON.parse(nzbnSearch.entity);

// Access specific properties
var address = entityData.registeredAddress;
var directors = entityData.directors;

WARNING

Not all companies have complete data. Always check if properties exist before using them in your form logic.

---

Best Practice

1. Create a test form with the NZBN component
2. Search for a known company
3. Use JSON.parse() to examine the entity data structure
4. Identify which fields you need for your use case
5. Build form logic to extract and display relevant data