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.
Use the Getting started guide to find out how to access our sandbox (mock services) and test environments.
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:
|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.
|1||Validate a customer's IRD number||1|
|2||Confirm an IRD number belongs to the customer||1|
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.