Skip to main content

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

The period API provides information about 1 or more periods for an identified customer account. It is 1 of 7 APIs that, together, make up the customer services suite.

How customer services work


If you have any questions about the period API or using gateway services for the period API, email us at GatewayServices@ird.govt.nz

How the period API works

When integrated through our gateway services, the period API provides information about a customer’s account periods. The period service accepts an account ID and account type, and an optional date range. It returns information about each period of the specified account or, if a date range is specified, it returns information about periods within that date range only. This information includes:

  • period start and end dates
  • the account or product type
  • filing frequency
  • whether a notice of assessment has been issued
  • whether a return has been filed or is still expected
  • the value of any default assessment.

An extended attribute list is returned for income tax accounts, which includes:

  • a balance date
  • extension of time details
  • provisional tax details
  • imputation or Māori Authority credit amounts.

The period API can only be used by:

  • the customer the account is associated to
  • a user with delegated access to the customer’s account
  • an intermediary who’s linked to the customer’s account
  • government agencies with a memorandum of understanding that allows them access to customer account level data.

Some customers may split their individual account access across delegated users. This means a user may not be able to see all accounts for a specific customer.

The period API enables the above users to query Inland Revenue’s period 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 period API

The period API provides the following capabilities through defined API operations and API paths.

API operation API path Description
POST /list Returns the information of periods for an identified customer account.

Period API business use cases

The following are examples of how to use the period API to achieve specific business outcomes. The sequence of operations, the order in which they should be called, is indicated in the column of each operation.

Number Use case POST /list Parameters
1 Retrieve details for all periods for a given customer account that I am authorised to access. 1
  • Account ID
  • Account type
2 Retrieve details for a single period for a given customer account that I am authorised to access. 1
  • Account ID
  • Account type
  • 'From' date (where date is within required start period)
  • 'To' date (where date is within required end period)
3 Retrieve account data for a range of periods for a given customer account that I am authorised to access. 1
  • Account ID
  • Account type
  • 'From' date (where date is within required start period)
  • 'To' date (where date is within required end period)

Supporting services

Identity and access services

Returns and information

Income Tax

Notifications