Skip to main content

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

The bank account API enables the creating and deleting of the refund bank account for an identified customer’s 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 bank account API or using gateway services for the bank account API, email us at [email protected]

How the bank account API works

The bank account API requires the account API to be integrated.

The bank account API enables the refund bank account held at the customer account level to be added and deleted. It requires the account ID for the addition or deletion of a refund bank account. The account ID is available through a call to the account API.

Note that the add function is effectively an update function if a refund bank account already exists on the customer account. It replaces the existing refund bank account with the added refund bank account in this scenario.

The bank account 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 bank account API enables the above users to update 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 bank account API

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

API operation API path Description
POST /bank

This operation either:

  • adds a refund bank account to the identified customer account if there is not already a refund bank account on the customer account
  • replaces an existing refund bank account on the identified customer account.
DELETE /bank Deletes the refund bank account from the identified customer account.

Bank account API business use cases

The following are examples of how to use the bank 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 /bank DELETE /bank Dependencies
1 Add the refund bank account to an identified customer account. 1 Customer account ID has been obtained from the account API.
2 Update the refund bank account to an identified customer account. 1 Customer account ID has been obtained from the account API.
3 Remove the existing refund bank account from an identified customer account. 1 Customer account ID has been obtained from the account API.

Supporting services

Identity and access services

Returns and information

Income Tax

Notifications