Manage employee addresses

When onboarding a new employee, you must provide two addresses to ensure accurate tax calculations during payroll processing:

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.

The effective_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.

Sample request:

curl --request POST \
     --url https://api.gusto-demo.com/v1/employees/employee_id/home_addresses \
     --header 'X-Gusto-API-Version: 2024-04-01' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {access_token}' \
     --header 'content-type: application/json' \
     --data '
{
  "street_1": "300 3rd Street",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94107",
  "effective_date": "2022-01-31",
  "courtesy_withholding": false
}
'

Sample response:

{
  "uuid": "{employee_address_uuid}",
  "version": "{version}",
  "employee_uuid": "{employee_uuid}",
  "street_1": "300 3rd Street",
  "street_2": "",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94107",
  "country": "USA",
  "active": true,
  "effective_date": "1970-01-01",
  "courtesy_withholding": false
}

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:

curl --request PUT \
     --url https://api.gusto-demo.com/v1/home_addresses/{home_address_uuid} \
     --header 'X-Gusto-API-Version: 2024-04-01' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {access_token}' \
     --header 'content-type: application/json' \
     --data '
{
  "version": "94b4d50fbc8f9c0fdcda677f136cca0f",
  "street_1": "1234 Milky Way",
  "city": "Albany",
  "state": "NY"
}
'

Sample response:

{
  "uuid": "{employee_address_uuid}",
  "version": "{version}",
  "employee_uuid": "{employee_uuid}",
  "street_1": "1234 Milky Way",
  "street_2": "",
  "city": "Albany",
  "state": "NY",
  "zip": "94107",
  "country": "USA",
  "active": true,
  "effective_date": "2022-01-31",
  "courtesy_withholding": false
}

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:

curl --request GET \
     --url https://api.gusto-demo.com/v1/employees/employee_id/home_addresses \
     --header 'X-Gusto-API-Version: {version}' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {access_token}' \

Sample response:

[
  {
    "uuid": "{employee_address_uuid}",
    "version": "{version}",
    "employee_uuid": "{employee_uuid}",
    "street_1": "300 3rd Street",
    "street_2": "",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94107",
    "country": "USA",
    "active": false,
    "effective_date": "1970-01-01",
    "courtesy_withholding": false
  },
  {
    "uuid": "{employee_address_uuid}",
    "version": "{version}",
    "employee_uuid": "{employee_uuid}",
    "street_1": "1234 Milky Way",
    "street_2": "",
    "city": "Albany",
    "state": "NY",
    "zip": "94107",
    "country": "USA",
    "active": true,
    "effective_date": "2022-01-31",
    "courtesy_withholding": false
  }
]

Work address

The work address of an employee will determine a company’s state tax liability. The effective_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.

Sample request:

curl --request POST \
     --url https://api.gusto-demo.com/v1/employees/employee_id/work_addresses \
     --header 'X-Gusto-API-Version: 2024-04-01' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {access_token}' \
     --header 'content-type: application/json' \
     --data '
{
  "location_uuid": "{company_location_uuid}",
  "effective_date": "2023-05-15"
}
'

Sample response:

{
  "uuid": "{work_address_uuid}",
  "employee_uuid": "{employee_uuid}",
  "location_uuid": "{location_uuid}",
  "effective_date": "2020-01-31",
  "active": true,
  "version": "{version}",
  "street_1": "977 Marks Viaduct",
  "street_2": "Apt. 958",
  "city": "Pink Hill",
  "state": "NC",
  "zip": "28572",
  "country": "USA"
}

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.

Sample request:

curl --request PUT \
     --url https://api.gusto-demo.com/v1/work_addresses/work_address_uuid \
     --header 'X-Gusto-API-Version: {version}' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {access_token}' \
     --header 'content-type: application/json' \
     --data '
{
  "version": "{version}",
  "location_uuid": "{location_uuid}",
  "effective_date": "2023-05-15"
}
'

Sample response:

{
  "uuid": "{work_address_uuid}",
  "employee_uuid": "{employee_uuid}",
  "location_uuid": "{location_uuid}",
  "effective_date": "2020-01-31",
  "active": true,
  "version": "{version}",
  "street_1": "977 Marks Viaduct",
  "street_2": "Apt. 958",
  "city": "Pink Hill",
  "state": "NC",
  "zip": "28572",
  "country": "USA"
}

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:

curl --request GET \
     --url https://api.gusto-demo.com/v1/employees/employee_id/work_addresses \
     --header 'X-Gusto-API-Version: {version}' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {access_token}' \

Sample response:

[
  {
    "uuid": "{work_address_uuid}",
    "employee_uuid": "{employee_uuid}",
    "location_uuid": "{location_uuid}",
    "effective_date": "2021-01-01",
    "active": false,
    "version": "{version}",
    "street_1": "91678 Farrell Meadow",
    "street_2": "Apt. 835",
    "city": "Phoenix",
    "state": "AZ",
    "zip": "85016",
    "country": "USA"
  },
  {
    "uuid": "{work_address_uuid}",
    "employee_uuid": "{employee_uuid}",
    "location_uuid": "{location_uuid}",
    "effective_date": "2022-01-01",
    "active": false,
    "version": "{version}",
    "street_1": "800 Adolfo Gardens",
    "street_2": "Suite 419",
    "city": "Bremen",
    "state": "AL",
    "zip": "35033",
    "country": "USA"
  }
]

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.

curl --request DELETE  
     --url <https://api.gusto-demo.com/v1/work_addresses/{work_address_uuid}>  
     --header 'accept: application/json'  
     --header 'authorization: Bearer access_token'

Home address

Create an employee’s home address

📘What is courtesy withholding?

Update an employee’s home address

Get an employee’s home address

Work address

Create an employee’s work address

📘

Update an employee’s work address

📘

Get an employee’s work address

Delete an employee’s work address

📘
What is courtesy withholding?