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 (like a tax agent, bookkeeper or payroll bureau) so the intermediary can act on their behalf.
About the intermediation service
The intermediation service is a SOAP web service that 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.
If you have any questions about using gateway services for the intermediation service, email [email protected]
Intermediation service software development kit (SDK)
This SDK helps you integrate:
- the schema (XSD) and supporting WSDL for the return service
- the build pack to view data definitions and response status codes
- sample request and response messages
- test scenarios
- test data.
Intermediation service software developer kit on GitHub
Use the Getting started guide to find out how to access our sandbox (mock services) and test environments.
Gateway services capability
The intermediation service provides the following capabilities through defined service operations on the gateway services:
| Service operation | Description |
|---|---|
| Link |
Enables:
|
| Delink |
Enables:
|
| Update |
Enables:
|
| 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 business use cases
The following are examples of sequences of the gateway return service operations that could be used to achieve a specific business outcome.
Keys
- Gateway service operations: RCL = Retrieve Client List, RC = Retrieve Client
- The numbers for each use case are the order in which these operations should be called when using this services.
| Use case | Gateway service operation | ||||
|---|---|---|---|---|---|
| Link | Delink | Update | RCL | RC | |
| 1. Retrieve complete list of clients and then request to link a new client to a client list. | 2 | 1 | |||
| 2. Link an existing client’s customer master to a client list. | 1 | ||||
| 3. Retrieve a client’s details (such as client accounts they have access to, if mail or disbursements are redirected to them) and then update client details. | 2 | 1 | |||
| 4. Remove a client from a client list. | 1 | 2 | |||
| 5. View lists of clients that have been approved or are pending approval (authorised payroll bureaus only) | 1 | ||||
| 6. Move a client to another client list the intermediary manages. | 1 | ||||
Supporting services
Moving between Inland Revenue sites
Heads up. We're taking you to our old site, where the page you asked for still lives