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 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.
For access to myIR File Upload and Gateway Services detailed technical documentation, register your organisation or login to Gateway Customer Support Portal using the links below.
Use the Getting started guide to find out how to access our sandbox (mock services) and test environments.
Gateway service capability for the BIC 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 and the 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 |