Make a payment
Software providers Kaiwhakarato Pūmanawa Rorohiko

Intermediation service

Intermediation is the process of linking an account or customer record belonging to an individual or organisation to a client list of a business intermediary (such as a tax agent, bookkeeper, payroll bureau etc) so the intermediary can act on their behalf

Information about the intermediation service

The intermediation service through the gateway services enables intermediaries to:

  • Link, delink or update the intermediary client list to their clients' accounts or customer master
  • retrieve clients and client lists that have already been established.

Intermediaries can use this service to create and manage links from a client list to a customer master or their accounts on any tax product.

Find out more about the types of intermediaries and what they can do with Inland Revenue

Gateway services capability for the intermediation service

The intermediation service provides the following capabilities through defined service operations on the gateway services:

Service operation Description
Link Enables linking of
  • a business intermediary's client list to a client account
  • a business intermediary's client list to the customer master of the client.
Delink Enables delinking of
  • a business intermediary's client list to a client account
  • a business intermediary's client list from the customer master of the client.
Update Enables
  • updating of a business intermediary's ability to redirect mail or disbursements on a client account
  • switching of a client account between a business intermediary's client lists.
Retrieve client list Enables retrieving of client lists belonging to a business intermediary as well as all of the clients in each list. This can be filtered by client account type or client list ID.
Retrieve client Enables retrieving of the client attributes between a business intermediary and a linked client or client accounts. This can be filtered by a client’s account type.

Intermediation service software development kit (SDK)

View and download the Intermediation Service software developer kit (SDK) to help you integrate:

  • test scenarios
  • test data
  • the schema (xsd) and supporting wsdl for the return service.

Download the intermediation service build pack to view:

  • data definitions of each operation
  • response status code definitions.

Identity and Access service

Supporting information

SOAP API architecture of gateway services

Learn about our soap architecture that we offer through gateway services and how we authorise identity and access to our application types.

Learn how to manage myIR logins for authorised representatives of an organisation so that access tokens can be generated for gateway services.

Intermediation service business use cases

The following use cases are examples of sequences of the gateway service operations that can be used to achieve a specific business outcome when using the intermediation service.

Number Use cases Link Delink Update Retrieve Client List Retrieve Client
1 An authorised Business Intermediary is able retrieve their complete list of clients and then request to link a new client to a client list. 2     1  
2 An authorised Business Intermediary is able to link an existing client’s customer master to a client list. 1        
3 An authorised Business Intermediary is able retrieve a client’s details (eg client accounts they have access to, if mail or disbursements are redirect to them) and then update client details.     2   1
4 An authorised Business Intermediary is able remove a client from a client list.   1 2    
5 An authorised Payroll Bureau is able to view lists of clients that have been approved or are pending approval.       1  
6 An authorised Business Intermediary is able to move a client to another client list they manage.     1