---
title: "Update an employee's home address"
method: PUT
path: "/v1/home_addresses/{home_address_uuid}"
tags: ["Employee Addresses"]
---

# Update an employee's home address

`PUT /v1/home_addresses/{home_address_uuid}`

## Request

- Base URL: `https://api.gusto-demo.com`
- URL: `https://api.gusto-demo.com/v1/home_addresses/{home_address_uuid}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/gusto/apis/gusto-api/docs/v1/home_addresses/:home_address_uuid/put.ts> (a function with typed inputs; its response is checked against the schema)

The home address of an employee is used to determine certain tax information about them. Addresses are geocoded on create and update to ensure validity.

Supports home address effective dating and courtesy withholding.

scope: `employees:write`

## Path parameters

- `home_address_uuid` string, required

## Headers

- `X-Gusto-API-Version` '2026-06-15'

## Request body

- object
  - `version` string, required: The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for information on how to use this field.
  - `street_1` string
  - `street_2` string, nullable
  - `city` string
  - `state` string
  - `zip` string
  - `effective_date` string, date, nullable
  - `courtesy_withholding` boolean

## Response `200`

successful

- EmployeeAddress
  - `uuid` string, required: The UUID of the employee address
  - `employee_uuid` string: The UUID of the employee
  - `effective_date` string, date: The date the employee started living at the address.
  - `courtesy_withholding` boolean: Determines if home taxes should be withheld and paid for employee.
  - `street_1` string
  - `street_2` string, nullable
  - `city` string
  - `state` string
  - `zip` string
  - `country` string
  - `active` boolean: The status of the location. Inactive locations have been deleted, but may still have historical data associated with them.
  - `version` string, required: The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for information on how to use this field.
  - `warnings` WarningObject[]: An array of warning objects that provide additional information about the address. Warnings do not prevent the address from being saved.
    - `error_key` string: Specifies where the warning occurs. Typically identifies the attribute or parameter related to the warning.
    - `category` string: Specifies the type of warning. Can be used to build custom warning handling.
    - `message` string: Provides details about the warning. The message can be surfaced directly to the end user.

## Other responses

- `404`: Not Found
- `422`: Unprocessable 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](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.

## Changes

- **2026-11-03** `f98575fa2a5e`: 1 info
  - added the optional property `warnings` to the response with the `200` status

[Operation history](https://skmtc.dev/gusto/apis/gusto-api/changes/v1/home_addresses/:home_address_uuid/put.md)

---

[API](https://skmtc.dev/gusto/apis/gusto-api.md) - [All operations](https://skmtc.dev/gusto/apis/gusto-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gusto/apis/gusto-api/revisions/f98575fa2a5e?raw)