IRD number validation service

The IRD number validation service validates a customer’s IRD number, identity and contact information and provides an assessment if it’s likely to be correct.

It is important to note that this service does not provide an IRD number as a response to a validation request.

You'll need to be compliant with our information disclosure policies to use these services.

Information disclosure

If you have any questions about the IRD number validation service or using gateway services email [email protected].

How the IRD number validation service works

A service user submits an IRD number and related identity attributes. The service uses matching logic to work out whether the IRD number reasonably belongs to the customer whose identity attributes have been supplied, then confirms whether there's a match or not.

Identity attributes for IRD number validation

The identity attributes that need to be supplied are:

• IRD number
• classification: the type of entity, such as individual, company or trust
• date: either the date of birth (for individuals) or the date of incorporation (for incorporated entities)
• name: either the first and last name (for individuals) or the registered name of the entity (for non-individuals)
• address: either the residential address (for individuals) or the entity's registered address (for non-individuals)
• NZBN - New Zealand business number (this is optional). The NZBN is a publicly accessible identifier allocated to incorporated companies and some other types of non-individual business entities. Other business types such as sole traders can also choose to get an NZBN.

Software developer kit (SDK)

View and download the IRD number validation service software developer kit to help you integrate:

• test scenarios
• test data
• sample request and response messages
• the Open API YAML file
• the build pack that provides the data definitions for the request and response messages.

IRD number validation service software developer kit (SDK) on GitHub

Use the Getting started guide to find out how to access our sandbox (mock services) and test environments.

Getting started guide

Gateway service capability for the IRD number validation service

The gateway service is the IRD number validation service API. It provides the following capabilities through defined service operations:

IRD number validation service business use cases

The following use cases are examples of requests to the gateway IRD number validation service operations that could be used to achieve a specific business outcome.

Supporting services

Approved digital service providers who have provided a mutual TLS certificate can submit requests to the identity and access service. No authentication service is required.

Identity and access services