NZBN API

The New Zealand Business Number (NZBN) API provides a range of operations for getting information about a New Zealand business, updating details, managing watchlists, and managing business authorities. There is no fee for using this API.

What is the NZBN?

The NZBN Register contains information about New Zealand businesses, including all companies and other entity types from Companies Office registers, all public sector entities, and sole traders, partnerships and trusts that have chosen to register for an NZBN. You can find out more on the NZBN website.

Other NZBN services

To get full data for all companies and other registered businesses you can request bulk data access. Once approved you can log in and download files containing all business information in JSON or CSV format used by the API. Files are updated on a monthly basis.

This can be useful for an initial data load into your own local database, data can then be kept current by using the API to search for business changes and getting the latest details for any updated businesses. 

You may also find the NZBN Business Match service useful to match NZBNs to a list of your business contacts.

Read more about NZBN data services.

Using the API

Follow these steps to get up and running:

Read the technical details

View the API definition in our developer portal here. You can also download the definition for viewing in Swagger Editor, SwaggerHub, or other tools.

Subscribe to the API

Log in and subscribe to the NZBN API Product. Refer to the table below to determine which subscription method is most appropriate for your needs. Our API support team may request further information before the subscription can be approved.

Generate an API subscription key

For full details on how to generate an API subscription key please see here.

Once your subscription has been approved you will be able use your API credentials to successfully call the API. Use the sandbox key and sandbox endpoints in your software development. Once you've completed testing simply use your production keys to access the live service.

Generate an OAuth2 token if required

There are three options for subscribing to the API. For most users who only need to search and get public information from the register the subscription key method is all that's needed. In some cases a subscription that also requires an OAuth2 token may be necessary:

  • Use the two-legged OAuth subscription if you need to have the additional security of a short-life access token, e.g. if your subscription key might be exposed to users of your product. Technical details of how to generate a two-legged OAuth2 token are available here.

  • Some API functions require a three-legged OAuth subscription as shown below. These are generally functions where an end-user of your product needs to make updates to entities they have authority over. To update the Primary Business Data of an entity the API end user needs to also have appropriate business authority.
    Technical details of how to generate a three-legged OAuth2 token are available here.

Test environment

A sandbox test environment is available for use during development of products that use the NZBN API.

To call the sandbox environment access tokens should be generated using your sandbox credentials. Once you have generated an access token call the endpoint of the environment you wish to target.

Note: Sandbox data is not a mirror of production data. The sandbox environment contains a mixture of test cases and old Companies Register data (prior to 2010). NZBNs allocated to businesses in sandbox may have identical numbers to NZBNs allocated in production, however the sandbox data will be unrelated to the production business.

API functionality

NZBN data

The NZBN register is made up of Primary Business Data (PBD). This is information that businesses are most often asked to share with other businesses and government. Public PBD is made available for searching on the NZBN Register for corporate, public and unincorporated entities. Not all PBD is mandatory and will only be available on the register where voluntarily provided, e.g. trading names, trading areas, industry classification and website.

Note: Some PBD can be provided but made private by the business so that it cannot be searched for on the public NZBN Register. A user with appropriate authority, using a three-legged OAuth token, can view their private business data from the NZBN API.

Disclaimer

The information returned by the NZBN API relates to entities carrying on business in New Zealand and has been drawn from other registers (such as the Companies Register) and government agencies. While the Ministry of Business, Innovation and Employment (MBIE) has attempted to facilitate efficient collection of that information, MBIE is not liable for the accuracy of this information. 

ETags

NZBN uses ETags to enable efficient retrieval of data, optionally allowing API consumers to retrieve detailed data only if it has been updated since the last time they requested the same information. Many of the API operations return an ETag header that can be stored by API consumers and sent in the If-None-Match header the next time the API operation is called for the same entity. The ETag associated with the entity is changed whenever the entity is updated.

The API will return the full requested data when the If-None-Match header is omitted from a request or if the ETag provided in the header does not match the current ETag for the entity. If the entity information has not been updated since the API consumer last retrieved the data then the provided ETag will still match the current ETag and the API will send an empty status 304 Not Modified response to indicate that the consumer already has the current data and does not need to retrieve it again.

Example

An API consumer has previously retrieved details for NZBN 9429000106078 and stored the value of the response ETag header, 7f898a5b-904b-3b48-9cf9-fddb6bb4c5e6. The next time the consumer software is asked to get details for 9429000106078 it sends the ETag value so that data is only returned if the stored information is still current.

Endpoint
GET {host}/gateway/nzbn/v5/entities/9429000106078
Headers
Accept: application/json
If-None-Match: 7f898a5b-904b-3b48-9cf9-fddb6bb4c5e6
Ocp-Apim-Subscription-Key: {subscription-key}
Response
HTTP/1.1 304 Not Modified

The data has not been changed since the consumer last retrieved it and it is safe to used the stored information without needing to download and process the response content again. If the information had changed the response would have status 200 OK and would contain the detailed data in the response body.

Organisation parts

Organisation Parts allow further detailed information to be provided for different physical, functional or digital locations of a business. Each Organisation Part is assigned an Organisation Part Number which, like the NZBN, is a unique 13 digit Global Location Number (GLN). Read more about Organisation Parts.

Every Organisation Part can have the following information associated with it depending on what the business chooses to enter:

  • Organisation Part Name

  • Organisation Part Purpose

  • Status (Active or Inactive)

  • Addresses

  • Contact details- email addresses and phone numbers

  • GST Number

API operations are available which provide the ability to:

  • Create new Organisation Parts for an NZBN entity

  • Search and View the details of Organisation Parts

  • Update Organisation Part data

Depending on its use, the organisation part and its associated data can be made public, kept private, or shared with other selected NZBN entities.

Note: To create and maintain organisation parts, the end user will need to have the appropriate business authority.

In some cases fees may apply to create more than two organisation parts for an NZBN entity. More information on these fees, and when a fee is applicable, is provided on the NZBN website.

Watchlists

There are two ways to use the API to find out when businesses have been registered or updated: create a watchlist or run a change event search.

A watchlist will send you an email or an API push notification when changes occur to a defined list of NZBNs. The watchlist can also be set up to notify of any new business registrations, or notify of any changes across an entire business register (e.g. the Companies Register).

The notification message will include the NZBN and name of the business, the type and date of the change, and the new value for the updated data. E.g. when details of a company's directors are updated the notification will include the full information for the company directors after the update.

Refer to the watchlist operations in the API definition for more detail of how to create and maintain watchlists. The definition for the push notification can be downloaded below:

NZBN watchlist notification - API definition.yaml

The following rules are followed to ensure delivery of watchlist push notifications:

  • Each delivery attempt will allow two minutes for a notification to be acknowledged by a 200 response from the recipient's client.

  • A notification will retry five times before delivery is considered to have failed. Retries will be sent at 20, 90, 180, 300, and 450 minutes from the original attempt.

  • When a notification has failed the maximum retries the watchlist will be suspended and an email will be sent to the watchlist administrator.

  • Notification records are still created while a watchlist is suspended but delivery is not attempted.  

  • The watchlist delivery can be resumed after any client issues have been resolved by setting the suspended flag to false using the PUT /watchlists/{watchlistId} operation. The watchlist will start sending notifications from the point that the watchlist was suspended.

  • A watchlist will be automatically end-dated if it has been suspended for one month without being resumed by the watchlist administrator.

A change event search is a search of the NZBN register to return a list of NZBNs that have been updated in a specified time period. The search can be filtered for a specific type of change or type of business. The response is an array of change items in the same format as a watchlist push notification: the NZBN and name of the business that has been updated, the type and date of the change, and the new value for the updated data. 

Note: Not all business types can currently be used in watchlists and change event searches. As these legacy business registers are modernised they will become available. Refer to the API definition for details of which business types can be used. 

Maintenance window

Reduced levels of service or outages may occur during the New Zealand Companies Office weekly maintenance window. These regularly occur from 9pm to 11pm on Wednesday. The duration can last longer if required so it is recommended to offset any required batch jobs from this period.

The sandbox environment may experience brief outages during and after business hours when software releases for NZBN and the source registers are carried out. 

Known limitations

There are some known limitations with the NZBN API. These will be addressed in future maintenance releases of the API or the source registers that supply data to NZBN.

Version history

Changes to the NZBN API definition are covered in the table below. The 'API Design Version' is the version of the Swagger definition used in API versions v4 and v5, which differ only in their authentication methods.

Reference information

Data types

Details of the following data types are described in the NZBN API reference data document.

  • Entity type / source register

  • Entity status

  • Change event / watchlist notification types

  • Address mapping

  • Trading area

NZBN format

Each NZBN is a 13 digit Global Location Number (GLN) provided by GS1 New Zealand. The last digit is a check digit which can be calculated using the method shown on the GS1 website.

Business Industry Classification

Business Industry Classification (BIC) code is a way of classifying a business entity by their main activity. Activity means the service or product the business entity provides to others. Further information on BIC codes can be found on the Business Industry Classification Code website.

A list of BIC codes can be downloaded here:

Business Industry Classification (BIC) codes 2022.zip