The name API enables the creating, updating and deleting of the customer's names. It is 1 of 8 APIs that, together, make up the customer services suite.
How the name API works
The name API requires the customer API to be integrated.
The name API enables the preferred name and trading name of a customer to be added, updated and deleted. It requires either:
- the customer ID for the addition of a name
- a name ID for the update or deletion of a name.
The name ID is available through a call to the customer API. The name API does not allow any access to the legal name of a customer.
The name 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 name API enables the above users to update Inland Revenue’s customer data from their native systems, and to avoid the use of manually facilitated channels.
For access to myIR File Upload and Gateway Services detailed technical documentation, register your organisation or login to Gateway Customer Support Portal using the links below.
Use the Getting started guide to find out how to access our sandbox (mock services) and test environments.
Gateway service capability for the name API
The name API provides the following capabilities through defined API operations and API paths.
| API operation | API path | Description |
|---|---|---|
| POST | /name | Adds a name of a given type (preferred or trading) to the customer data set. |
| PUT | /name | Updates the details of an existing name in the customer data set. |
| DELETE | /name | Deletes a given name from the customer data set. |
Name API business use cases
The following are examples of how to use the name 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 /name | PUT /name | DELETE /name | Dependencies |
|---|---|---|---|---|---|
| 1 | Add a preferred name to a customer. | 1 | Customer does not already have a preferred name. | ||
| 2 | Update an existing preferred name for a customer. | 1 | Name ID for update has been obtained from the customer API. | ||
| 3 | Remove an existing preferred name for a customer. | 1 | Name ID for removal has been obtained from the customer API. |