Skip to main content
Check out our new content, navigation and design for digital service providers.

COVID-19 - Level 2 If you have been affected by COVID-19, we may be able to help. Find out more

The income service enables digital service providers to retrieve a customer’s income profile data reported to Inland Revenue.

If you have any questions about the income service including using gateway services API, email GatewayServices@ird.govt.nz

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.

Getting started guide

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 income 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

Supporting services

Identity and access services

Accounting income method (AIM)

Income tax

Investment income reporting

Payday filing