The customer API provides general information about a customer. It is 1 of 8 APIs that, together, make up the customer services suite.
If you have any questions about the customer API or using gateway services for the customer API, email us at [email protected]
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.
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 |