Skip to main content

Delays to response times: It's taking longer than usual to answer calls and myIR messages, including for unclaimed money. You may be able to use self-service options in myIR. You can also find information on our website by typing in what you want to do in the search bar. Thank you for your understanding. Log in to myIR

The BIC API enables the adding / updating and ceasing of the BIC codes for an identified customer’s account. It is 1 of 8 APIs that together make up the customer services suite.

How customer services work

If you have any questions about the BIC API or using gateway services for the BIC API, email us at [email protected]

How the BIC API works

The BIC API requires the customer API to be integrated. The customer API is used to request the customer's data, each of which is identified using a synthetic key. The associated synthetic key is then used in the BIC API request to add, update and cease BIC codes for an identified customer’s account.

The BIC 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 BIC 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 BIC API provides the following capabilities through defined API operations.

API operation Description
Add/Update

Associates a new BIC code to a specific IRD number. If the IRD number provided belongs to an account with an existing BIC code, that code will be ceased and the new BIC code added. This message type uses the resource “/bic” and the “POST” HTTP method.

Cease Ceases an existing BIC code indicating that the business activity associated with this BIC code ended. This message type uses the resource “/bic” and the “DELETE” HTTP method.

BIC API business use cases

The following are examples of use cases of the BIC API operation that could be used to achieve specific business outcomes. The numbers for each use case are the order in which these operations should be called when using this API.

Number Use case Post Delete
1 Add a new BIC code to a specific IRD number or customer account. 1
2 Update a BIC code to a specific IRD number or customer account. 1
3 Ceases an existing BIC code indicating that the business activity associated with this BIC code ended. 1

Supporting services

Identity and access services

Returns and information

Income Tax

Notifications

Last updated: 14 May 2022
Jump back to the top of the page