Update an employee’s external identifier

This endpoint allows changing an employee’s external identifier (employeeId).

PUT /api/v1/businesses/{businessId}/employees/{employeeId}/new-employee-id/{newEmployeeId}

Besides the business external identifier (businessId), the URL must specify the employee current identifier (employeeId) and the new one (newEmployeeId). The request does not include a body or query params.

Request example

PUT /api/v1/businesses/BUSINESSID/employees/CURRENTID/new-employee-id/NEWID

If the request is successful, the response will be 204 No Content.

The employeeId is the key used to reference employees: after making this change, integrations must use the new employeeId.

Error codes

In addition to the common errors, this endpoint can return the following codes:

Code Message Description

404 Not Found

Person <employeeId> does not exist

The current employeeId indicated does not exist in the business (the literal interpolates the identifier sent).

409 Conflict

Employee <newEmployeeId> already exists in business <businessId>

The newEmployeeId indicated is already in use in the business (the literal interpolates both identifiers).

Useful links

What is an employee?