Skip to main content

Service update myIR, SPK2IR and our phone lines will be unavailable until the start of business on Monday 1 March for a planned system update. Find out more

COVID-19 - Alert Level 1 If you've been affected by COVID-19, we may be able to help. Find out more

The address API enables the creating, updating and deleting of the address of a customer or an account. It is 1 of 7 APIs that, together, make up the customer services suite.

How customer services work


If you have any questions about the address API or using gateway services for the address API, email us at GatewayServices@ird.govt.nz

How the address API works

The address API requires the customer or account API to be integrated.

The address API enables the addresses held at either the customer level or the customer account level to be added, updated and deleted. It requires either:

  • the customer ID or account ID for adding an address to a customer or account
  • an address ID for the update or deletion of an address from a customer or account.

The customer ID or account ID is available through a call to the customer API or account API, respectively. The address ID is available through a call to either the customer API or the account API.

The address API can only be used by:

  • the customer the data is associated to
  • a user with delegated access
  • an intermediary who’s linked to the customer
  • government agencies with a memorandum of understanding that allows them access to customer account level data.

The address API enables the above users to update Inland Revenue’s customer or account data from their native systems, and to avoid the use of manually facilitated channels.

Software developer kit (SDK)

View and download the software developer kit (SDK) for the customer services suite 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.

Software developer kit (SDK) on GitHub - customer services suite

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 address API

The address API provides the following capabilities through defined API operations and API paths.

API operation API path Description
POST /address

Adds an address of a given type (physical or postal) to either the identified:

  • customer
  • account.
PUT /address

Updates the provided details to the identified address for either the:

  • customer
  • account.
DELETE /address

Deletes the details of the identified address for either the:

  • customer
  • account.

Address API business use cases

The following are examples of how to use the address API to achieve specific business outcomes. The sequence of operations, the order in which they should be called, is indicated in the column of each operation.

Number Use case POST /address PUT /address DELETE /address Dependencies
1 Add a postal address to a customer. 1 Customer does not already have a postal address.
2 Update an existing postal address for a customer. 1 Address ID for update has been obtained from the customer API.
3 Update an existing postal address for a customer account. 1 Address ID for update has been obtained from the account API.
4 Remove an existing postal address for a customer. 1 Address ID for removal has been obtained from the customer API.
5 Remove an existing postal address for a customer account. 1 Address ID for removal has been obtained from the account API.

Supporting services

Identity and access services

Returns and information

Income Tax

Notifications