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 account API provides either a list of accounts for an identified customer or information about a single customer account. It is 1 of 7 APIs that, together, make up the customer services suite.

How customer services work


An account represents a tax type (for example, income tax) or a product (for example, KiwiSaver).

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

How the account API works

When integrated through our gateway services, the account API provides general information about customer accounts. The account API accepts either a customer ID or an account ID. When a customer ID is provided, the account API will return a list of account IDs associated with the customer. When an account ID is provided, the account API returns information about that identified account including:

  • account status
  • account type (tax or product name)
  • filing details
  • start and stop dates
  • physical address
  • postal address
  • primary contact details (contact and phone)
  • secondary contact details (contact and phone)
  • refund bank account.

The account API can only be used by:

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

Some customers may split their individual account access across delegated users. This means a user may not be able to see all accounts for a specific customer. 

The account API enables the above users to query Inland Revenue’s customer 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 account API

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

API operation API path Description
POST /list Returns a list of accounts for an identified customer.
POST /account Returns the information of an identified customer account.

Account API business use cases

The following are examples of how to use the account 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 /list POST /account
1 Retrieve a list of accounts for an identified customer that I am authorised to access. 1
2 Retrieve account data for an account that I am authorised to access but do not have the account ID. 1 2
3 Retrieve account data for an account that I am authorised to access and already have the account ID. 1

Supporting services

Identity and access services

Returns and information

Income Tax

Notifications