Companies Entity Role Search API

Companies-Entity-Role-Search is a REST API that searches the New Zealand Companies Register by director or shareholder name. 

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 Entity Role Search API Product. Our API support team may request further information before the subscription can be approved.

Generate an API subscription key and call the API

For full details on how to generate an API subscription key, and optionally an OAuth2 bearer token for additional security, 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.

Request and response

The API has a single operation for searching for parties in roles with one or more companies. A request includes three search query parameters:

  • name  the name of the person or entity, in some role associated with a company, to search for. At least two characters must be specified.  The search is NOT case sensitive. Refer to the search guidelines section for more details.

  • role-type the type of role to search for. One of SHR, DIR or ALL must be specified corresponding to shareholder, director or both, respectively.  Note that a director will always be a person, while a shareholder may be a person or an entity/organisation.

  • registered-only can optionally be used to return only directors/shareholders that have an active role in at least one registered company. Note: details of all companies associated with that director or shareholder will be returned regardless of each company status.

Results are paginated, page size and number parameters are set using the page and page-size parameters. 

Response format

Both JSON and XML based response formats are supported and will be returned if the 'Accept' HTTP request header is set to 'application/json' or 'application/xml', respectively.

XML is provided for backwards-compatibility reasons for previous consumers of older Companies Office APIs, any new development should use JSON format as any API enhancements may not always be reflected in the XML response.

Shareholder search

If a shareholder has multiple separate shareholder allocations in a company, the API only returns details of the first allocation. The API is intended to return the companies that an entity or person has a shareholding in, not necessarily the full details of all their shareholdings in that company. For comprehensive information on the associated company, including full shareholding details, use the NZBN API.

In some specific instances a shareholder search can return a result where the entity's role is company director only. This indicates that the director of the company was previously also a shareholder, but has since relinquished their shareholding.

Director search

In some specific instances a director search can return a result where the entity's role is shareholder only. This indicates that the shareholder of the company was previously also a director, but has since relinquished their directorship.

Company status

See the Documentation tab of the NZBN API for a full list of all company statuses that can be returned by the API.

Search guidelines

The details of the name search behaviour are more complex than can be documented fully here. The fundamental rules and some practical examples are provided below, along with recommendations on the best way to return relevant results.

The text supplied in the name parameter can match against:

  • first, middle, and last names of directors or individual shareholders

  • current name and previous names of organisation shareholders.

Searching for an individual

One or more names can be provided in the name parameter. The order that these are supplied in impacts how the search is carried out. When the search string includes more than one term, an exact match is performed on the first terms, and a partial match (starts with) on the last term.

Recommended search format

To get the most relevant results enter the name parameter in the form:

LastName FirstName [optional MiddleName/MiddleInitial]

E.g. Smith Belinda Jane  or Smith Belinda J

Single name search

When one name is provided in the name parameter director and/or individual shareholders may be returned. See further below for details of organisation shareholders that may also be returned in the results.

A 'starts with' search is performed against last name, and exact match against first and middle names. 

Two term search

If you know the first and last name of the director/shareholder these can be entered in either order. Results are returned regardless of the middle name.

When the name parameter is in the form name=Name1 Name2 results for individuals are returned where:

  • Name1 is an exact match for the first, a middle, or last name; and

  • Name2 is an exact match for a middle or last name, or first name starts with Name2

Multiple term search

A middle initial or middle name(s) may be included in the search to get more precise results. Note that people’s names are often entered inconsistently in the Companies Register, and the same person may be entered with their middle name for one company, and without it for another.

There are two ways that the names can be entered in the search, with different behaviour .

  1. FirstName MiddleName LastName - Exact matches against names as entered

  2. LastName FirstName MiddleName - Exact matches for last and first names, 'starts with' search on middle name

Results may also be returned where the names entered match against combinations of middle names and first/last name.

Searching for an organisation shareholder

One or more names can be provided in the name parameter. Results will be returned where each name matches against any of the current or historic names.

A fuzzy match is used and will return names similar to the search name.