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.
company_uuid from the response of the
partner_managed_companies endpoint, you can make the following API calls to create and update employee information:
The get the employee's onboarding status endpoint retrieves an employee's onboarding status, showing the required steps to complete the employee's onboarding.
You can use the create an employee endpoint to create an employee record in Gusto using basic employee information you already collect. This includes
ssn. After the employee is created, subsequent calls can be made to update additional information like their
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.
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
GETthe 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:
Head of Household
Exempt from withholding
Married, but withhold as Single(does not apply to
- 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)
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_up_to must always be
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.
The create an employee bank account endpoint creates an employee bank account. Required fields to make this request include name,
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
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
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.
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
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
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.
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
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:
- 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:
More more information on jobs and compensations available here.
After creating an employee and their job(s) you should reconcile their
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.
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.
Updated 2 months ago