Skip to main content
Check out our new content, navigation and design for digital service providers.

COVID-19 - Level 2 If you have been affected by COVID-19, we may be able to help. Find out more

We're prioritising digital service providers whose design solutions make it easy for end users to meet their tax obligations and receive their social policy entitlements. We'll contact you to discuss how your software achieves this before we start any gateway services integration.

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.

If you have any questions about the IRD number validation service or using gateway services email GatewayServices@ird.govt.nz.

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:

Service operation Description
ValidateIRDPost Validates the IRD number and confirms if it matches the identity attributes provided.

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.

Number Use case ValidateIRDPost
1 Validate a customer's IRD number 1
2 Confirm an IRD number belongs to the customer 1

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