Skip to main content

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

The customer services suite offers 3 view options for customer data held by Inland Revenue.

Customer Data relating to an individual or non-individual entity registered with Inland Revenue.
Account Data relating to a specific tax type (such as income tax) or product (such as KiwiSaver) for a customer.
Period Data relating to a specific period for a customer’s account.

Additionally, the customer services suite offers 10 update options for selected elements of customer data held by Inland Revenue.

Customer

  • Names (preferred name and trading name).
  • Physical address.
  • Postal address.
  • Primary contact details (contact and phone).
  • Secondary contact details (contact and phone).

Account

  • Physical address.
  • Postal address.
  • Primary contact details (contact and phone).
  • Secondary contact details (contact and phone).
  • Refund bank account.

The update options can only be used in conjunction with the associated view option. For example, a request to update customer level data must be preceded by a request to view customer level data. This is because the response to the view request contains the input keys required for the update request.

Note that there are no update options for period level data.

How the customer APIs connect with each other

There are 7 application programming interface (API) services that, together, make up the customer services suite. They provide general information about a customer and enable updating of specific elements of that information.

Read-only APIs Level linked at Associated update APIs
Customer API Customer level Name API
Address API
Contact API
Account API Account level (including products) Address API
Contact API
Bank account API
Period API Period level None, as this sits under the account level

Read-only APIs

The 3 read-only APIs must be implemented to allow users to query general information at the customer, account or product, or period levels.

These must also be implemented for the Update APIs to function.

Update APIs

The 4 update APIs only perform updates (including creates and deletes). They must be implemented to give authorised users update, create and delete functions.