Skip to content

Addresses

Reading addresses works with READ. Creating, updating, or archiving them requires WRITE (Authentication & scopes).

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.

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.

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.

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.

  • Devices — shipping_address_id, assigned_address_id, and location.
  • API reference — Addresses and User addresses tags.