Addresses
Reading addresses works with READ. Creating, updating, or archiving them requires WRITE (Authentication & scopes).
Company addresses
Section titled “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 /addresseslists the company’s current addresses;GET /addresses/:address_idreturns one.POST /addressescreates one.countrydefaults toFR.is_default: truemakes it the company’s single default address.is_hqmarks the head office; it is read-only here.
Administrative area
Section titled “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
Section titled “Updates keep delivery history”PATCH /addresses/:address_id changes only the fields you send:
- Contact, label, type, comment, default, and
user_idchanges 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
Section titled “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=42returns the employee’s{ user_id, address_id }link; load the address withGET /addresses/:address_id. Withoutuser_id, it lists every link of the company. - Add:
POST /addresseswithtype: "HOME"anduser_id. Assigning an address replaces the employee’s previous one, which stays in the company’s addresses. - Update:
PATCH /addresses/:address_idas for any address. Senduser_idto 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
Section titled “Next steps”- Devices —
shipping_address_id,assigned_address_id, andlocation. - API reference — Addresses and User addresses tags.

