The prescribed investor rate (PIR) calculator service provides a suggested prescribed investor rate for an individual customer.
You'll need to be compliant with our information disclosure policies to use these services.
Information disclosure
If you have any questions about the PIR calculator service or using gateway services for the PIR calculator service, email [email protected]
How the PIR calculator service works
Income from PIE (portfolio investment entity) investments is taxed at a rate called the prescribed investor rate or PIR.
Because PIRs are chosen when a customer opens an account but the tax is squared up at a later date, the PIR may be out of date. The PIR calculator service can assist in this scenario by providing a suggested prescribed investor rate for an individual customer.
The customer in consultation with their PIE provider is responsible for using the correct prescribed investor rate.
Software developer kit (SDK)
View and download the PIR calculator service software developer kit to help you integrate:
- sample request and response messages
- the Open API YAML file
- the build pack that provides the data definitions for the request and response messages
- test scenarios
- test data.
PIR calculator service software developer kit (SDK) on GitHub
Use the Getting started guide to find out how to access our sandbox (mock services) and test environments.
Gateway service capability for the PIR calculator service
The gateway service is the PIR calculator service API. It provides the following capabilities through a defined service operation:
| Service operation | Description |
|---|---|
| Post | Retrieves a customer's suggested prescribed investor rate from Inland Revenue. |
The identity attributes that need to be supplied are:
- the individual investor's IRD number
- the PIE's IRD number
- the investor’s name, date of birth and address (only for non-KiwiSaver PIEs)
PIR calculator service business use cases
The following are examples of sequences of the gateway PIR calculator service operations that could be used to achieve a specific business outcome. The numbers for each use case are the order in which these operations should be called when using this services.
| Number | Use case | Post |
|---|---|---|
| 1 | View a customer's prescribed investor rate | 1 |