Companies API
The Companies API is provided for users to reserve company names, incorporate new companies, and maintain companies on the New Zealand Companies Register that they have authority over. This API currently includes functions to enable the filing of an annual return and maintaining director, shareholding and general company details such as addresses. It can also be used to reserve a company name and incorporate a new company.
Use the NZBN API for retrieving public details of New Zealand companies and other business types. To get a download of full data for all companies and other registered businesses go to the NZBN website. Other APIs are available for searching company directors and shareholders or disqualified directors.
Software that uses this API for filing annual returns must support the 'end to end' process. This means it will offer the ability for software users to review the current company details held on the Companies Register and determine if an update is required before filing the annual return. Where an update is required, it should be done prior to filing the annual return.
Only New Zealand companies are currently supported within this API. Maintenance of overseas companies on the New Zealand register, those with entity type ASIC or Non-ASIC, are not supported.
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 Companies Register API Product using the Authorisation code flow/3-legged OAuth method. 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 for user authorisation
When calling the API you must have both a subscription key and a three-legged OAuth bearer token associated with a Companies Register user that has provided consent for your product to access their data.
Consent is provided by the end user logging in with the RealMe account that they use on the Companies Office site. The 3-legged token that is generated in this process can then be used in future requests for maintaining any company that the user has authority over. Refer to the fee payment section below to see how the official fees for annual return, name reservation, or company incorporation are processed.
Technical details of how to generate this token are available here.
Fee payment
Direct debit
Unless a payment is handled by credit card the Companies office will invoice users at the end of the month and collect payment using direct debit on the 20th of the following month.
The API validates that an active direct debit payment facility is in place against the end user, or an organisation that the end user is associated with in the Companies Register, each time an annual return is filed from your product. Payment will be charged to the organisation account if an organisation ID is specified in the annualReturn.fileAnnualReturnForOrganisation attribute, otherwise the payment will be charged to the individual's account.
To retrieve the applicable organisation ID you should use the NZBN API GET/organisations operation. This operation has no parameters and will return every organisation associated with the end user associated with the three-legged OAuth token used in the API call.
Credit card
The optional parameters paymentMethod and redirectURL can be used in the relevant POST requests to specify the credit card payment method. In this case the API will respond with a URL for MBIE's credit card payment provider. The user should be sent to this URL to complete their payment details.
Upon completion or cancellation of the credit card payment the user will be redirected to the redirectURL you specified in the request. The URL will also include a query parameter to indicate success or failure of the transaction. In case the user is disrupted before being returned to the redirectURL you will need to poll the Companies API to check the status of the transaction request.
A Companies Office invoice with confirmation of the payment will be emailed to the user upon successful payment by credit card.
For full details of the credit card payment process refer to the Companies API credit card payment document.
Company incorporation
The API can be used to create a company, set up all details, and incorporate the company. Before you incorporate a New Zealand company with the Companies Office, you must reserve a company name. Fees are applicable for reserving a name and incorporating a company.
The reference files below provide an outline for carrying out company incorporation API operations. You can use these in conjunction the API specification to assist in mapping the end to end process that needs to be completed when incorporating a company.
Companies API workflows (5 February 2018).zip
Companies API - company incorporation.pdf
Company maintenance
The API can be used to maintain all aspects of a company, including updating addresses, directors, shareholding details, and filing annual returns. The NZBN API can optionally be used to retrieve lists of companies that a user, or a user's organisation, has authority to maintain.
The reference files below provide outlines for carrying out company maintenance and annual returns. You can use these in conjunction with the API specification to assist in mapping the end to end process of maintaining a company and then filing the annual return.
Companies API workflows (5 February 2018).zip
Companies API - company maintenance.pdf
Development and test resources
A sandbox test environment is available for use during your product development. Please contact us for assistance on setting up test cases and gaining access to the test Companies Register.
The reference document below provides details of error codes and descriptions that may be returned.
