When onboarding a new employee, you must provide two addresses to ensure accurate tax calculations during payroll processing:Documentation Index
Fetch the complete documentation index at: https://gusto-preview.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
- Home address: The employee’s primary residence, used to determine state and local tax obligations.
- Work address: The location where employees perform their job, which also impacts payroll tax withholdings.
Home address
An employee’s home address is used to determine applicable tax obligations. Gusto geocodes the address on create and update to ensure accuracy and location-based compliance. The home address supports effective dating and courtesy withholding, allowing for precise tax handling even when an employee moves.Create an employee’s home address
Create an employee’s home address when an employee first onboards to determine the tax by calling the POST /v1/employees/{employee_id}/home_addresses endpoint. Theeffective_date signifies when the employee began living at this location. ”courtesy_withholding”: true indicates there is an active courtesy withholding at this location.
What is courtesy withholding?
Federal law prevents the same wages from being taxed by more than one state. If an employee lives in one state and works in another, some states have reciprocal agreements so the employee only pays income tax to one state—usually the employee’s home state.Employers can choose courtesy withholding, electing that Gusto withholds and pays an employee’s home state taxes instead.Learn more about reciprocity and courtesy withholdings here.Update an employee’s home address
Employees may relocate during their time with a company, requiring updates to their home or work addresses. These changes can affect both employee and employer tax responsibilities. To stay compliant, always use effective dating when recording address changes. This ensures accurate tax setup and helps prevent issues such as payroll reversals or last-minute corrections due to late address updates. If an employee moves or their home address changes, you can update their existing address using the PUT /v1/home_addresses/{home_address_uuid} endpoint. Sample request:Get an employee’s home address
Check whether the employee’s home address has been created or updated by using the GET /v1/employees/{employee_id}/home_addresses endpoint. Sample request:Work address
The work address of an employee will determine a company’s state tax liability. Theeffective_date signifies when the employee began working at a given location.
Create an employee’s work address
When an employee first onboards, create an employee’s work address by using the POST /v1/employees/{employee_id}/work_addresses endpoint.The address must first exist at the company level to create an employee’s work address. If it does not, you’ll need to create a company location by calling the POST /v1/companies/{company_id}/locations endpoint.
Update an employee’s work address
If a company relocates, each employee’s work address must be updated to reflect the new company location by using the PUT /v1/work_addresses/{work_address_uuid} endpoint.Keeping work addresses up to date is important for accurate tax calculations and compliance. Use the
effective_date parameter to ensure changes are applied at the correct time.Get an employee’s work address
Get the employee’s work address by using the GET /v1/work_addresses/{work_address_uuid} endpoint. The address with the status"active": true, is the employee’s current active work address.
Sample request:
Delete an employee’s work address
Use the DELETE /v1/work_addresses/{work_address_uuid} endpoint to delete an employee’s work address. An employee’s active work address cannot be deleted so you’ll need to designate another work address to be active first.I-9 Verification Using Flows Calculate a reasonable salary for S Corp owner-employees