The income service enables digital service providers to retrieve a customer’s income profile data reported to Inland Revenue.
How the income service works
The income service enables access to a customer's income and tax data from all known income sources for a specific date range. It returns income data that consists of the income source, date income was recognised, income type, amount, and any deductions from that income.
Income data is accessible by an intermediary who's linked to the customer’s income tax account or the customer to whom the income belongs.
When integrated through our gateway services it can be used to match investment and income data to what we have recorded.
Software developer kit (SDK)
View and download the income service software developer kit 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.
Income 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 services capabilities for the income service
The gateway service used for the income service is the income API. It provides the following capabilities through defined service operations:
| Service operation | Description |
|---|---|
| Post | Retrieves income information from Inland Revenue. Requires an IRD number, a 'from' date, and an optional 'to' date. |
The income service business use case
The following is an example of a business use case on the income service that could be used to achieve a specific business outcome.
| Number | Use case | API Call: Post |
|---|---|---|
| 1 | As an intermediary, request income information for a customer and receive this information, then match the income data to what you've recorded for the customer. | 1 |