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.

Considerations

If the current employee employeeId does not exist, the request will return a 404 Not Found error, with the message Person does not exist.

If the specified newEmployeeId is already in use in the business, the request will return a 409 Conflict error, with the message Employee already exists in business.

Useful links

What is an employee?