Sign in

v1

latestOpenAPI 3.1.02026-07-243113441.2 MB
Employees

Create an employee

Create an employee.

scope: employees:manage

post/v1/companies/{company_id}/employees

Path parameters

company_idstring required

Company ID

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

first_namestring required
middle_initialstring
last_namestring required
emailstring email nullable

The employee's personal email address. Required if self_onboarding is true.

work_emailstring email

The employee's work email address.

date_of_birthstring date
ssnstring
preferred_first_namestring
self_onboardingboolean

If true, employee is expected to self-onboard. If false, payroll admin is expected to enter in the employee's onboarding information

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"
    }
  ]
}