# Addresses

Reading addresses works with **READ**. Creating, updating, or archiving them requires **WRITE** ([Authentication & scopes](/authentication/)).

## Company addresses

An address is a place Fleet ships to or picks up from: an office, an employee's home, a PO box, or an external storage. Devices, cart lines, and parcels reference addresses by id.

- **`GET /addresses`** lists the company's current addresses; **`GET /addresses/:address_id`** returns one.
- **`POST /addresses`** creates one. `country` defaults to `FR`. `is_default: true` makes it the company's single default address.
- **`is_hq`** marks the head office; it is read-only here.

## Administrative area

For the United States, Canada, Italy, Australia, Mexico, and Japan, send **`administrative_area`**: the state, province, or prefecture as its local code (`MI`) or its ISO 3166-2 code (`IT-MI`). It is optional for Spain and refused elsewhere. A missing or unknown area returns `INVALID_ADDRESS` (400).

`state` is deprecated: it is read only when `administrative_area` is absent.

## Updates keep delivery history

**`PATCH /addresses/:address_id`** changes only the fields you send:

- Contact, label, type, comment, default, and `user_id` changes keep the **same id**.
- A change of **location** (street, zip, city, area, or country) archives the address, so delivered orders and devices keep pointing at where they actually went, and returns a **new address with a new id**. The old id then answers `ADDRESS_NOT_FOUND`.

Always store the id the response returns.

**`DELETE /addresses/:address_id`** archives the address the same way: it leaves lists, and past orders and devices keep it.

## Personal addresses

An employee has one personal address: a `HOME` address whose **`user_id`** names them. Every address response carries `user_id`, `null` when no employee lives there.

- **Read**: `GET /user-addresses?user_id=42` returns the employee's `{ user_id, address_id }` link; load the address with `GET /addresses/:address_id`. Without `user_id`, it lists every link of the company.
- **Add**: `POST /addresses` with `type: "HOME"` and `user_id`. Assigning an address replaces the employee's previous one, which stays in the company's addresses.
- **Update**: `PATCH /addresses/:address_id` as for any address. Send `user_id` to move the address to another employee. A location change returns a new id that keeps the employee.

The address takes the employee's name, email, and phone; a `phone` sent with `user_id` also updates the employee.

| Error | Status | When |
| --- | --- | --- |
| `USER_NOT_FOUND` | 404 | `user_id` is not an active user of your company |
| `ADDRESS_NOT_HOME` | 400 | `user_id` is sent for an address that is not `HOME` |
| `ADDRESS_HAS_ASSIGNED_USER` | 409 | `type` changes on a `HOME` address an employee lives at |

If your company syncs an HR software with Fleet, its next sync overwrites the personal addresses it supplies.

## Next steps

- [Devices](/devices/) — `shipping_address_id`, `assigned_address_id`, and `location`.
- **API reference** — **Addresses** and **User addresses** tags.