Locations in your module

Use your workspace's shared list of offices, yards and storage instead of keeping your own.

Copy page for AIUpdated November 21, 2026

Every company has places: an office, a few branches, a yard, a shop, a storage container out back. The workspace keeps one list of them, and every module reads the same list. So when your module asks "which yard?", it offers the same yards as HR, Equipment and everyone else, spelled the same way. Please don't build your own list of sites.

What's in the list

A Workspace Admin keeps the list in System settings › Locations. Each location has:

DetailExample
Name and codeSanta Ana Yard, santa_ana_yard
TypeRegion, Office, Branch, Yard, Shop, Storage or Other
InsideThe location it sits in: West Region › Santa Ana › Yard 2
Address and map spotStreet, city, state, zip, and a map position
Phone and notesOptional
ActiveClosed places are made inactive, never deleted

A company with one office has one row. A company with a hundred yards has a hundred. Either way, it's set up once.

Reading locations

Your module can read the list at any time, from a screen or from the server. You get each location with its full path (West Region › Santa Ana › Yard 2), its type, its address and its map position. Parents come before their children, so a nested picker is easy to draw.

  • In a picker, offer active locations only.
  • When showing old records, read inactive ones too, so a closed yard still shows its name instead of a blank.

Anyone signed in to the workspace can read the list. Only Workspace Admins can add or change locations; modules can't.

Linking a record to a location

Save the location's id on your record, not a copy of its name. Then:

  1. Your record always shows the current name, even if the location is renamed.
  2. Every module that links to the same place uses the same id, so reports can line them up by location.
  3. A closed location still labels your old records, because locations are never deleted.

Have records with an address? The location's map position works with the platform's maps too. See Charts, maps and 3D.

Ask the Module Builder

python
# For developers: read the list (active only by default)
locs = await list_locations("MY_MODULE", tenant_id)
every = await list_locations("MY_MODULE", tenant_id, include_inactive=True)
# each: id, code, name, location_type, path, depth, address, lat, lng, is_active, ...

From a screen, the same list comes from GET /api/v1/locations (add ?include_inactive=true for labels).

Good to know

  • Included. Reading locations costs nothing extra.
  • No list yet? Ask the Workspace Admin to add their places in System settings › Locations. Your picker fills in by itself.
  • Need more detail about a place, like a gate code or a bay count? Keep that in your own module's table, linked by the location's id.
  • Rooms or bays can be added as Storage or Other locations nested inside a building or yard.

Can't find what you need? Contact support.