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 customer API provides general information about a customer. 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 customer API or using gateway services for the customer API, email us at GatewayServices@ird.govt.nz

How the customer API works

When integrated through our gateway services, the customer API provides general information about an identified customer. The customer API accepts a customer ID (IRD number or other customer identifier) and returns high-level information for that customer including:

  • names (preferred name and trading name)
  • physical address
  • postal address
  • primary contact details (contact and phone)
  • secondary contact details (contact and phone)
  • start and stop dates
  • entity classification (for example, individual salary and wages, or non-individual limited partnership).

The customer 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.

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

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

API operation API path Description
POST /customer Returns the information of an identified customer.

Customer API business use cases

The following are examples of how to use the customer API to achieve specific business outcomes. All assume the user is authorised to access the customer's data. The sequence of operations, the order in which they should be called, is indicated in the column of each operation.

Number Use case POST /customer
1 Retrieve the customer addresses held by Inland Revenue. 1
2 Retrieve the customer contact details held by Inland Revenue. 1
3 Check the last time customer address, name or contact details held by Inland Revenue were updated. 1

Supporting services

Identity and access services

Returns and information

Income Tax

Notifications