Sign in

v1

latestOpenAPI 3.1.02026-07-243113441.2 MB
Employees

Update a historical employee

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

scope: employees:manage employees:write

put/v1/companies/{company_uuid}/historical_employees/{historical_employee_uuid}

Path parameters

company_uuidstring required

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

historical_employee_uuidstring required

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

Headers

X-Gusto-API-Version'2026-06-15'

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

Request body

versionstring required

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

first_namestring required

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

middle_initialstring

Single middle initial, if any.

last_namestring required

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

preferred_first_namestring

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

date_of_birthstring date required

Date of birth (YYYY-MM-DD).

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

emailstring email

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

Example request

{
  "version": "56d00c178bc7393b2a206ed6a86afcb4",
  "first_name": "Soren",
  "middle_initial": "A",
  "last_name": "Kierkegaard",
  "preferred_first_name": "Angel",
  "date_of_birth": "1995-05-05",
  "ssn": "123456294",
  "work_address": {
    "location_uuid": "1da85d35-1910-40a7-9c1f-8e2b3d4c5a6f"
  },
  "home_address": {
    "street_1": "55 Mission St",
    "street_2": "Floor 3",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94105"
  },
  "termination": {
    "effective_date": "2022-01-01"
  },
  "email": "soren.kierkegaard@example.com",
  "job": {
    "hire_date": "2020-01-01"
  },
  "employee_state_taxes": {
    "wc_covered": true,
    "wc_class_code": "051000"
  }
}

Response

Successful

uuidstring required

The UUID of the employee in Gusto.

first_namestring required
middle_initialstring nullable
last_namestring required
emailstring nullable

The personal email address of the employee. This is provided to support syncing users between our system and yours. You may not use this email address for any other purpose (e.g. marketing).

company_uuidstring

The UUID of the company the employee is employed by.

manager_uuidstring nullable

The UUID of the employee's manager.

versionstring

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

departmentstring nullable

The employee's department in the company.

terminatedboolean

Whether the employee is terminated.

two_percent_shareholderboolean nullable

Whether the employee is a two percent shareholder of the company. This field only applies to companies with an S-Corp entity type.

work_emailstring nullable

The work email address of the employee. This is provided to support syncing users between our system and yours. You may not use this email address for any other purpose (e.g. marketing).

onboardedboolean

Whether the employee has completed onboarding.

onboarding_status'onboarding_completed' | 'admin_onboarding_incomplete' | 'self_onboarding_pending_invite' | 'self_onboarding_invited' | 'self_onboarding_invited_started' | 'self_onboarding_invited_overdue' | 'self_onboarding_completed_by_employee' | 'self_onboarding_awaiting_admin_review' nullable

The current onboarding status of the employee

date_of_birthstring nullable
has_ssnboolean

Indicates whether the employee has an SSN in Gusto.

ssnstring

Deprecated. This field always returns an empty string.

phonestring nullable
preferred_first_namestring nullable
payment_method'Direct Deposit' | 'Check'

The employee's payment method

current_employment_status'full_time' | 'part_time_under_twenty_hours' | 'part_time_twenty_plus_hours' | 'variable' | 'seasonal' nullable

The current employment status of the employee. Full-time employees work 30+ hours per week. Part-time employees are split into two groups: those that work 20-29 hours a week, and those that work under 20 hours a week. Variable employees have hours that vary each week. Seasonal employees are hired for 6 months of the year or less.

historicalboolean
employee_codestring

The short format code of the employee

department_uuidstring nullable

The UUID of the department the employee is under

titlestring
hired_atstring date

The date when the employee was hired to the company

hidden_ssnstring
flsa_status'Exempt' | 'Salaried Nonexempt' | 'Nonexempt' | 'Owner' | 'Commission Only Exempt' | 'Commission Only Nonexempt'

The FLSA status for this compensation. Salaried ('Exempt') employees are paid a fixed salary every pay period. Salaried with overtime ('Salaried Nonexempt') employees are paid a fixed salary every pay period, and receive overtime pay when applicable. Hourly ('Nonexempt') employees are paid for the hours they work, and receive overtime pay when applicable. Commissioned employees ('Commission Only Exempt') earn wages based only on commission. Commissioned with overtime ('Commission Only Nonexempt') earn wages based on commission, and receive overtime pay when applicable. Owners ('Owner') are employees that own at least twenty percent of the company.

applicable_tax_idsnumber[]
partner_portal_invitation_sentboolean nullable

Whether an external partner portal invitation webhook has been sent for this employee. Only included when the include param has the portal_invitations value set.

Example response

{
  "eligible_paid_time_off": [
    {
      "accrual_unit": "Hour",
      "accrual_method": "unlimited",
      "accrual_period": "Year"
    }
  ]
}