Skip to main content

COVID-19 Alert Level 1 If you've been affected by COVID-19, we may be able to help. Find out more

The name API enables the creating, updating and deleting of the customer's names. 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 name API or using gateway services for the name API, email us at [email protected]

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.

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

Supporting services

Identity and access services

Returns and information

Income Tax

Notifications