Send Employee Information

📘

The bearer token should be specified via the Authorization HTTP header for these requests.

After creating the company via partner_managed_companies you can pass any employee information that you already collect using our API. If you do not already collect this information, you can build a UI in your application so the user can enter this information to pass along to Gusto. If using Onboarding Flows (Pre-built UI) this information will pre-populate fields in the Flow so the payroll administrator will not need to provide this information twice.

Using the company_uuid from the response of the partner_managed_companies endpoint, you can make the following API calls to create and update employee information:

Get Employee Onboarding Status

The get the employee's onboarding status endpoint retrieves an employee's onboarding status, showing the required steps to complete the employee's onboarding.

Create an Employee

You can use the create an employee endpoint to create an employee record in Gusto using basic employee information you already collect. This includes first_name, middle_initial, last_name, date_of_birth, email and ssn. After the employee is created, subsequent calls can be made to update additional information like their home_address, employee_bank_account, employee_payment_method, jobs, and compensations.

Update an Employee's Home Address

The home address of an employee is used to determine certain tax information about them. Use the update an employee's home address endpoint to set this.

Gusto only supports W2 employees based in the US at this time.

Update an Employee's Federal Taxes

The update an employee's federal taxes endpoint updates attributes relevant for an employee's federal taxes. These inputs will be used to calculate how much federal tax will be withheld from an employee's wages on payroll.

When updating an employee's federal taxes, the following information is needed:

• version (string) - The current version of the object. You can GET the current version via Get an employee's federal taxes.
• filing_status (string) - It determines which tax return form an individual will use and is an important factor in computing taxable income. One of: Single Married Head of Household Exempt from withholding Married, but withhold as Single (does not apply to rev_2020_w4 form).
• extra_withholding (string) - An employee can request an additional amount to be withheld from each paycheck.
• two_jobs (boolean) - If there are only two jobs (i.e., you and your spouse each have a job, or you have two), you can set it to true.
• dependents_amount (string) - A dependent is a person other than the taxpayer or spouse who entitles the taxpayer to claim a dependency exemption.
• other_oncome (string) - Other income amount.
• deductions (string)
• w4_data_type (string) - The version of the w4 form. Allowed values: rev_2020_w4(revised 2020 W4 form), pre_2020_w4(pre 2020 W4 form)

Update an Employee's State Taxes

The update an employee's state taxes endpoint updates attributes relevant for an employee's state taxes. These inputs will be used to calculate which state taxes and how much of each will be withheld from an employee's wages on payroll.

The data required to correctly calculate an employee's state taxes varies by both home and work location.

First, retrieve the attributes relevant for an employee's state taxes using the get an employee's state taxes endpoint. This API returns information about each question that must be answered grouped by state. Mostly commonly, an employee lives and works in the same state and will only have questions for a single state. The response contains metadata about each question, the type of answer expected, and the current answer stored in Gusto for that question.

Answers are represented by an array. Today, this array can only be empty or contain exactly one element, but is designed to allow for forward compatibility with effective-dated fields. Until effective dated answers are supported, the valid_from and valid_up_to must always be "2010-01-01" and null respectively.

From here, update an employee's state taxes based on the answers supplied by the end user. As described for the GET endpoint, the answers must be supplied in the effective-dated format, but currently only a single answer will be accepted - valid_from and valid_up_to must be "2010-01-01" and null respectively.

Create an Employee Bank Account

The create an employee bank account endpoint creates an employee bank account. Required fields to make this request include name, routing_number, account_number, and account_type (Checking, Savings). An employee can have multiple bank accounts and you can determine how an employee’s pay is split by updating the employee’s payment method.

Creating an employee bank account will automatically update an employee’s payment method from Check to Direct Deposit.

Update an Employee's Payment Method

The update an employee's payment method endpoint is used to update an employee’s payment method, or if the employee has setup multiple bank accounts, can update how they want to split their pay. Payments can be split by an Amount (dollar amount) or by a Percentage.

You can also set the payment priority, which is the order of priority for each payment split. "priority": 1 would be the first bank account to receive payment, for example.

Create an Employee's Job

Use the create a job endpoint to set the employee's job. A job is effectively an employee’s title or pay rate.

An employee can have multiple jobs in Gusto and each job_id is unique to an employee. Two employees cannot share the same job_id.

❗️

Prerequisites

The location needs to be created in advance of a job using create a company location.

The request to create a job should include a title, location_id, and hire_date. The hire_date can be the employee’s actual hire_date or the effective_date of the job if the employee has multiple jobs.

Creating a job automatically creates a non-exempt, hourly compensation of $0/hr. Compensation for a job should be updated in subsequent API call.

Update an Employee's Compensation

Once a job is created, use the update a compensation endpoint to set the employee's wage.

Compensations contain information on how much is paid out for a job. Jobs can have multiple compensations, but only one that is active. The current compensation is the one with the most recent effective_date.

When updating a compensation, the following information is needed:

• 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'. Allowed values: 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. Owners ('Owner') are employees that own at least twenty percent of the company. Allowed values: Exempt Salaried Nonexempt Owner.

More more information on jobs and compensations available here.

Employee Reconciliation

After creating an employee and their job(s) you should reconcile their employee_id and job_ids (and their respective compensations) and persist these in your database. This information is necessary to update payroll on an ongoing basis and will ensure the intended employee is being paid the correct wage.

Delete an Employee

If at any point you need to delete an employee who is in the middle of onboarding you can call the delete an onboarding employee endpoint. This is only intended to delete an employee that has not been fully onboarded, as deleting an onboarded employee “onboarded”: “true” is not permitted.