Skip to main content

​
Overview

Sites are hierarchical locations inside an organization. They form a tree under a root site (site-root-*). All site operations are org-scoped and site-access-scoped.

​
Schema (output)

Key fields returned by APIs: 
{
  id: string,
  name: string,
  createdAt: Date,
  updatedAt: Date,
  parentSiteId: string | null,
  country: string | null,
  city: string | null,
  address: string | null,
  unLocode: string | null,
  longitude: string | null,
  latitude: string | null,
  numberOfEmployees: number | null,
  floorAreaInM2: number | null,
  tags: string[] | null,
  metadata: Record<string, string> | null,
}
Note: longitude and latitude are strings in responses.

​
Hierarchy & Access

  • Root site is created per organization; cannot be deleted.
  • Effective access for a user = assigned sites + all descendants (via OrganizationUserSite).
  • Listing (sites.list) returns only sites in your accessible set (optionally including root as “Organization”).

​
Operations

  • List sites: sites.list({ includeRoot?: boolean })
  • Create site: sites.create({ name, organizationId, parentSiteId?, ... })
  • Update site: sites.update({ id, name, ... })
  • Delete site: sites.delete({ id, cascade?: boolean }) (soft-delete; cascade to delete descendants)
  • Import CSV: sites.import({ organizationId, csvContent }) (bulk create with validation)
All operations validate organization and site access (RBAC + ABAC) and use RLS.

​
CSV Import

Supported columns (header examples):
  • id?, name (required)
  • parentSiteId? (must exist in DB or in the same CSV)
  • country?, city?, address?, unLocode?
  • longitude?, latitude?
  • numberOfEmployees?, floorAreaInM2?
  • tags? (comma or | separated)
  • metadata_* (e.g., metadata_sapId → { sapId: "..." })
Behavior:
  • Validates and topologically sorts rows (parents before children); detects cycles.
  • Batch inserts per dependency level.
  • Returns success/failed counts and detailed errors (with row numbers).

​
Best Practices

  • Keep the hierarchy shallow; assign region nodes to managers, leaf nodes to collectors.
  • Populate numberOfEmployees and floorAreaInM2 for intensity calculations.
  • Use tags and metadata_* for external IDs and filtering.
  • Prefer cascade delete only when you’re sure about removing descendants.

​
Gotchas

  • Root site cannot be deleted.
  • Coordinates are strings; convert to numbers if you need math.
  • Deleting a site is soft-delete (sets deletedAt).

​
See Also

  • Organization (settings, membership)
  • Organization User (roles)
  • Organization User Site (site assignments and effective access)