Update a historical employee

put

https://api.gusto-demo.com/v1/companies/{company_uuid}/historical_employees/{historical_employee_uuid}

Update a historical employee, an employee that was previously dismissed from the company in the current year.

scope: employees:manage employees:write

Path Params

company_uuid

string

required

The UUID of the company that will employ this historical record.

historical_employee_uuid

string

required

The UUID of the historical employee returned from create or list responses.

Body Params

Request body for creating or updating a historical employee—someone who already separated from the company and must appear on year-to-date or tax filings without receiving ongoing payroll.

Send this object under the JSON root key employee. All dates are ISO 8601 (YYYY-MM-DD). Use a work_address.location_uuid returned from your company locations API for an active work site.

version

string

required

The current version of the object. See the versioning guide for information on how to use this field.

first_name

string

required

Legal first name as it appears on government-issued identification.

middle_initial

string

Single middle initial, if any.

last_name

string

required

Legal last name as it appears on government-issued identification.

preferred_first_name

string

Preferred given name for display; omit when the same as legal first name.

date_of_birth

date

required

Date of birth (YYYY-MM-DD).

ssn

string

required

Nine-digit U.S. Social Security number without dashes or spaces. Must pass Gusto/SSA validation in production; use a valid test SSN in sandbox environments.

work_address

object

required

Primary work location for this historical employment row.

home_address

object

required

Residential address on file for tax withholding and compliance mail.

termination

object

required

End of the historical employment period.

string

Optional. When provided, stored on the employee record for notifications and profile.

job

object

required

Hire date for the historical job used to build employments and filings.

employee_state_taxes

object

Workers' compensation fields for Washington (WA) or Wyoming (WY) when the work address is in those states; omit when not applicable.

Headers

X-Gusto-API-Version

string

enum

Defaults to 2026-02-01

Determines the date-based API version associated with your API call. If none is provided, your application's minimum API version is used.

Allowed:

Responses

200Successful

404Not Found The requested resource does not exist. Make sure the provided UUID is valid.

422Unprocessable Entity This may happen when the body of your request contains errors such as invalid_attribute_value, or the request fails due to an invalid_operation. See the Errors Categories guide for more details.