Create an employee

post https://api.gusto-demo.com/v1/companies/{company_id}/employees

Create an employee.

scope: employees:manage

Responses

Response body

object

uuid

string

required

The UUID of the employee in Gusto.

first_name

string

required

middle_initial

string | null

last_name

string

required

string | null

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_uuid

string

The UUID of the company the employee is employed by.

manager_uuid

string | null

The UUID of the employee's manager.

version

string

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

department

string | null

The employee's department in the company.

terminated

boolean

Whether the employee is terminated.

two_percent_shareholder

boolean | null

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

onboarded

boolean

Whether the employee has completed onboarding.

onboarding_status

string

The current onboarding status of the employee

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

onboarding_documents_config

object

Configuration for an employee onboarding documents during onboarding

uuid

string | null

The UUID of the onboarding documents config

i9_document

boolean

Whether to include Form I-9 for an employee during onboarding

jobs

array of objects

jobs

object

uuid

string

required

The UUID of the job.

version

string

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

employee_uuid

string

The UUID of the employee to which the job belongs.

hire_date

string

The date when the employee was hired or rehired for the job.

title

string | null

Defaults to null

The title for the job.

primary

boolean

Whether this is the employee's primary job. The value will be set to true unless an existing job exists for the employee.

rate

string

The current compensation rate of the job.

payment_unit

string

The payment unit of the current compensation for the job.

current_compensation_uuid

string

The UUID of the current compensation of the job.

two_percent_shareholder

boolean

Whether the employee owns at least 2% of the company.

state_wc_covered

boolean | null

Whether this job is eligible for workers' compensation coverage in the state of Washington (WA).

state_wc_class_code

string | null

The risk class code for workers' compensation in Washington state. Please visit Washington state's Risk Class page to learn more.

compensations

array of objects

compensations

object

uuid

string

required

The UUID of the compensation in Gusto.

version

string

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

job_uuid

string

The UUID of the job to which the compensation belongs.

employee_uuid

string

The UUID of the employee to which the compensation belongs.

rate

string

The dollar amount paid per payment unit.

payment_unit

string

The unit accompanying the compensation rate. If the employee is an owner, rate should be 'Paycheck'.

Hour Week Month Year Paycheck

flsa_status

string

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.

Exempt Salaried Nonexempt Nonexempt Owner Commission Only Exempt Commission Only Nonexempt

effective_date

string

The effective date for this compensation. For the first compensation, this defaults to the job's hire date.

adjust_for_minimum_wage

boolean

Indicates if the compensation could be adjusted to minimum wage during payroll calculation.

minimum_wages

array of objects

The minimum wages associated with the compensation.

minimum_wages

object

uuid

string

The UUID of the minimum wage.

wage

string

The wage amount.

effective_date

string

The effective date of the minimum wage.

eligible_paid_time_off

array of objects

eligible_paid_time_off

object

name

string

The name of the paid time off type.

Vacation Hours Sick Hours Holiday Hours

policy_name

string

The name of the time off policy.

policy_uuid

string

The UUID of the time off policy.

accrual_unit

string

The unit the PTO type is accrued in.

accrual_rate

string

The number of accrual units accrued per accrual period.

accrual_method

string

The accrual method of the time off policy

accrual_period

string

The frequency at which the PTO type is accrued.

accrual_balance

string

The number of accrual units accrued.

maximum_accrual_balance

string | null

The maximum number of accrual units allowed. A null value signifies no maximum.

paid_at_termination

boolean

Whether the accrual balance is paid to the employee upon termination.

terminations

array of objects

terminations

object

uuid

string

required

The UUID of the termination object.

version

string

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

employee_uuid

string

The UUID of the employee to which this termination is attached.

active

boolean

Whether the employee's termination has gone into effect.

cancelable

boolean

Whether the employee's termination is cancelable. Cancelable is true if run_termination_payroll is false and effective_date is in the future.

effective_date

string

The employee's last day of work.

run_termination_payroll

boolean

If true, the employee should receive their final wages via an off-cycle payroll. If false, they should receive their final wages on their current pay schedule.

garnishments

array of objects

garnishments

object

uuid

string

required

The UUID of the garnishment in Gusto.

version

string

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

employee_uuid

string

The UUID of the employee to which this garnishment belongs.

active

boolean

Defaults to true

Whether or not this garnishment is currently active.

amount

string

The amount of the garnishment. Either a percentage or a fixed dollar amount. Represented as a float, e.g. "8.00".

description

string

The description of the garnishment.

court_ordered

boolean

Whether the garnishment is court ordered.

times

integer | null

Defaults to null

The number of times to apply the garnishment. Ignored if recurring is true.

recurring

boolean

Defaults to false

Whether the garnishment should recur indefinitely.

annual_maximum

string | null

Defaults to null

The maximum deduction per annum. A null value indicates no maximum. Represented as a float, e.g. "200.00".

total_amount

string | null

Defaults to null

A maximum total deduction for the lifetime of this garnishment. A null value indicates no maximum.

pay_period_maximum

string | null

Defaults to null

The maximum deduction per pay period. A null value indicates no maximum. Represented as a float, e.g. "16.00".

deduct_as_percentage

boolean

Defaults to false

Whether the amount should be treated as a percentage to be deducted per pay period.

garnishment_type

string | null

The specific type of garnishment for court ordered garnishments.

child_support federal_tax_lien state_tax_lien student_loan creditor_garnishment federal_loan other_garnishment

child_support

object | null

Additional child support order details

custom_fields

array of objects

Custom fields are only included for the employee if the include param has the custom_fields value set

custom_fields

object

string

required

company_custom_field_id

string

required

This is the id of the response object from when you get the company custom fields

name

string

required

type

string

required

Input type for the custom field.

text currency number date radio

description

string

value

string

required

selection_options

array of strings | null

An array of options for fields of type radio. Otherwise, null.

selection_options

date_of_birth

string | null

has_ssn

boolean

Indicates whether the employee has an SSN in Gusto.

ssn

string

Deprecated. This field always returns an empty string.

phone

string | null

preferred_first_name

string | null

payment_method

string

Defaults to Check

The employee's payment method

Direct Deposit Check

work_email

string | null

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

current_employment_status

string | null

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.

full_time part_time_under_twenty_hours part_time_twenty_plus_hours variable seasonal

404

Not Found

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

`invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the Errors Categories guide for more details.

xxxxxxxxxx
curl --request POST \
     --url https://api.gusto-demo.com/v1/companies/company_id/employees \
     --header 'X-Gusto-API-Version: 2024-04-01' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

xxxxxxxxxx
}
{
  "uuid": "4b3f930f-82cd-48a8-b797-798686e12e5e",
  "first_name": "Isom",
  "middle_initial": null,
  "last_name": "Jaskolski",
  "email": "dane7757869450111550@botsford.net",
  "company_uuid": "a007e1ab-3595-43c2-ab4b-af7a5af2e365",
  "manager_uuid": "5e53e257-c8d6-45aa-aa8a-ec99283a3acd",
  "version": "1c7ba9d62c8bafbfff998ffccad5d296",
  "department": "Stage Hand",
  "department_uuid": "56260b3d-c375-415c-b77a-75d99f717193",
  "terminated": false,
  "two_percent_shareholder": false,
  "onboarded": true,
  "onboarding_status": "onboarding_completed",
  "onboarding_documents_config": {
    "uuid": null,
    "i9_document": false
  },
  "jobs": [
    {
      "uuid": "428a653a-0745-4db4-9c80-558288d416fa",
      "version": "6c0ed1521e8b86eb36bd4455a63a2dac",
      "employee_uuid": "f0689739-1985-49f3-b9ba-84562e71e85f",
      "current_compensation_uuid": "c9fd719b-8b07-48f3-8a4c-f447d2c59669",

201Example response

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.

`invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the Errors Categories guide for more details.