Location Hierarchy

Overview

Xenia’s location system supports multi-level hierarchies to model your organizational structure. Locations can represent physical sites, regions, departments, or any organizational unit relevant to your operations.

Key Concepts

Location Levels

Location levels define the hierarchy structure (e.g., Country → Region → Site → Floor → Room). Each level has:

Title: Display name for the level
Order: Position in hierarchy (lower = higher in tree)
isSite: Marks the level as the primary operational site

Location Hierarchies

Locations can belong to multiple hierarchies, enabling flexible organizational models:

Geographic hierarchy: Country → State → City → Building
Operational hierarchy: Division → Department → Team
Physical hierarchy: Building → Floor → Room

Location Level Operations

List Location Levels

Retrieve all location level definitions for your workspace.

curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/location-levels" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"

Response:

{
  "status": "success",
  "code": 200,
  "data": [
    {
      "id": "level-uuid-1",
      "title": "Region",
      "order": 1,
      "isSite": false,
      "WorkspaceId": "workspace-uuid"
    },
    {
      "id": "level-uuid-2",
      "title": "Site",
      "order": 2,
      "isSite": true,
      "WorkspaceId": "workspace-uuid"
    },
    {
      "id": "level-uuid-3",
      "title": "Floor",
      "order": 3,
      "isSite": false,
      "WorkspaceId": "workspace-uuid"
    }
  ]
}

Create Location Level

Add a new level to your location hierarchy.

curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/location-levels" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Building",
    "order": 2,
    "isSite": true
  }'

Field	Type	Required	Description
`title`	string	Yes	Display name for the level
`order`	number	No	Position in hierarchy (auto-incremented if not provided)
`isSite`	boolean	No	Marks as primary operational site (default: false)

Response:

{
  "status": "success",
  "code": 200,
  "data": {
    "id": "new-level-uuid",
    "title": "Building",
    "order": 2,
    "isSite": true,
    "WorkspaceId": "workspace-uuid"
  }
}

Permission Required: CAN_MANAGE_LOCATIONS

Update Location Level

Modify an existing location level.

curl -X PATCH "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/location-levels/{levelId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Campus",
    "isSite": true
  }'

Batch Update Location Levels

Update multiple levels at once (useful for reordering).

curl -X PUT "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/location-levels" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "levels": [
      { "id": "level-1", "order": 1 },
      { "id": "level-2", "order": 2 },
      { "id": "level-3", "order": 3 }
    ]
  }'

Delete Location Level

Remove a location level from the hierarchy.

curl -X DELETE "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/location-levels/{levelId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"

Deleting a location level may affect locations assigned to that level. Ensure no active locations reference the level before deletion.

Location CRUD Operations

List Locations

Retrieve all locations in your workspace. Returns a hierarchical tree structure by default.

curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/locations" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"

Query Parameters:

Parameter	Type	Description
`notree`	string	Return flat array instead of tree (`"true"`, `"1"`)
`onlySite`	string	Only return site-level locations (`"true"`, `"1"`)
`deleted`	string	Include soft-deleted locations (`"true"`, `"1"`)
`hierarchyId`	UUID	Filter by specific hierarchy
`locationLevelId`	UUID	Filter by specific level
`page`	number	Pagination page number
`perPage`	number	Items per page

Response (Tree Structure):

{
  "status": "success",
  "code": 200,
  "data": [
    {
      "hierarchyId": "hierarchy-uuid",
      "hierarchyName": "Geographic",
      "locations": [
        {
          "id": "loc-uuid-1",
          "name": "North America",
          "description": "NA Region",
          "LevelId": "level-uuid-1",
          "assetCount": 0,
          "Sublocations": [
            {
              "id": "loc-uuid-2",
              "name": "New York Office",
              "description": "NYC Headquarters",
              "LevelId": "level-uuid-2",
              "assetCount": 15,
              "Sublocations": []
            }
          ]
        }
      ]
    }
  ]
}

Permission Required: CAN_ACCESS_LOCATIONS

Get Location by ID

Retrieve details of a specific location.

curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/locations/{locationId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"

Response:

{
  "status": "success",
  "code": 200,
  "data": {
    "id": "location-uuid",
    "name": "New York Office",
    "description": "NYC Headquarters",
    "address": "123 Main Street, New York, NY 10001",
    "email": "[email protected]",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "isQREnable": true,
    "LevelId": "level-uuid",
    "ParentId": "parent-location-uuid",
    "WorkspaceId": "workspace-uuid",
    "UniqueLocationId": "unique-loc-uuid",
    "assetCount": 15,
    "attachments": ["https://storage.example.com/floor-plan.pdf"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-06-20T14:45:00Z"
  }
}

Create Location

Create a new location with optional sublocations.

curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/locations" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Chicago Office",
    "description": "Midwest Regional HQ",
    "address": "456 Lake Shore Dr, Chicago, IL 60611",
    "email": "[email protected]",
    "latitude": 41.8781,
    "longitude": -87.6298,
    "isQREnable": true
  }'

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Location name (must be unique within parent)
`description`	string	No	Location description
`address`	string	No	Physical address
`email`	string	No	Contact email
`latitude`	number	No	GPS latitude coordinate
`longitude`	number	No	GPS longitude coordinate
`isQREnable`	boolean	No	Enable QR code generation
`attachments`	string[]	No	URLs to attached files
`UniqueLocationId`	UUID	No	Unique ID for multi-hierarchy sharing
`Sublocations`	object	No	Nested sublocations structure
`hierarchies`	object[]	No	Hierarchy placements (see below)

Hierarchy Object:

Field	Type	Description
`hierarchyId`	UUID	Target hierarchy ID
`ParentId`	UUID	Parent location ID
`LevelId`	UUID	Location level ID
`memberIds`	string[]	User IDs to assign as members

Permissions Required: CAN_ACCESS_LOCATIONS AND CAN_CREATE_LOCATIONS

Update Location

Modify an existing location.

curl -X PATCH "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/locations/{locationId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Chicago HQ",
    "description": "Updated description",
    "address": "789 Michigan Ave, Chicago, IL 60611"
  }'

Permissions Required: CAN_ACCESS_LOCATIONS AND CAN_EDIT_LOCATIONS

Delete Locations

Soft delete one or more locations.

curl -X DELETE "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/locations" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "locationIds": ["location-uuid-1", "location-uuid-2"]
  }'

Permissions Required: CAN_ACCESS_LOCATIONS AND CAN_DELETE_LOCATIONS

Deleting a parent location will also delete all child locations in its subtree.

Location Groups

Location groups allow you to create logical groupings of locations that don’t follow the physical hierarchy (e.g., “High Priority Sites”, “24/7 Locations”).

List Location Groups

curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/location-groups" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"

Response:

{
  "status": "success",
  "code": 200,
  "data": [
    {
      "id": "group-uuid",
      "name": "High Priority Sites",
      "description": "Locations requiring enhanced monitoring",
      "Locations": [
        { "id": "loc-1", "name": "NYC Office" },
        { "id": "loc-2", "name": "Chicago Office" }
      ]
    }
  ]
}

Create Location Group

curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/location-groups" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "24/7 Operations",
    "description": "Locations with round-the-clock operations",
    "Locations": ["location-uuid-1", "location-uuid-2", "location-uuid-3"]
  }'

Permission Required: CAN_MANAGE_LOCATIONS

Update Location Group

curl -X PATCH "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/location-groups/{locationGroupId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Critical Sites",
    "Locations": ["location-uuid-1", "location-uuid-2"]
  }'

Delete Location Group

curl -X DELETE "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/location-groups/{locationGroupId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"

Common Workflows

Setting Up a Multi-Site Organization

Step 1: Create Location Levels

# Create levels in order
curl -X POST ".../location-levels" -d '{"title": "Region", "order": 1}'
curl -X POST ".../location-levels" -d '{"title": "Site", "order": 2, "isSite": true}'
curl -X POST ".../location-levels" -d '{"title": "Floor", "order": 3}'
curl -X POST ".../location-levels" -d '{"title": "Room", "order": 4}'

Step 2: Create Hierarchy

# Create with nested structure
curl -X POST ".../locations" \
  -d '{
    "name": "North America",
    "Sublocations": {
      "New York Office": {
        "Sublocations": {
          "Floor 1": {
            "Sublocations": {
              "Lobby": {},
              "Conference Room A": {}
            }
          }
        }
      },
      "Chicago Office": {
        "Sublocations": {
          "Floor 1": {},
          "Floor 2": {}
        }
      }
    }
  }'

Syncing Locations from External System

When integrating with CMMS, ERP, or property management systems:

# 1. Get all existing locations (flat list for easier comparison)
curl -X GET ".../locations?notree=true"

# 2. For each external location, check if exists by name
# 3. Create new or update existing
curl -X POST ".../locations" \
  -d '{
    "name": "External Site 123",
    "UniqueLocationId": "external-system-id-123",
    "description": "Synced from PropertyMgmt",
    "address": "100 External Ave"
  }'

Use UniqueLocationId to maintain a stable identifier for locations that exist in multiple hierarchies or external systems.

Best Practices

Plan your hierarchy before creating

Design your location levels and structure before importing data. Changing the hierarchy later requires moving locations and updating references.

Use meaningful level names

Choose level names that match your organization’s terminology. Users will see these names throughout the application.

Mark operational sites correctly

Set isSite: true on the level that represents your primary operational locations. This affects filtering and reporting.

Leverage location groups

Use groups for cross-cutting concerns (priority tiers, operational schedules) that don’t fit the physical hierarchy.

Include geographic data

Adding latitude/longitude enables map-based features and location-aware functionality.

Location Members - Assign users to locations
Asset Management - Manage assets at locations
Team Management - Organize users into teams

Getting Started

Workflows

Integrations

Overview

Key Concepts

Location Levels

Location Hierarchies

Location Level Operations

List Location Levels

Create Location Level

Update Location Level

Batch Update Location Levels

Delete Location Level

Location CRUD Operations

List Locations

Get Location by ID

Create Location

Update Location

Delete Locations

Location Groups

List Location Groups

Create Location Group

Update Location Group

Delete Location Group

Common Workflows

Setting Up a Multi-Site Organization

Syncing Locations from External System

Best Practices

Getting Started

Workflows

Integrations

​Overview

​Key Concepts

​Location Levels

​Location Hierarchies

​Location Level Operations

​List Location Levels

​Create Location Level

​Update Location Level

​Batch Update Location Levels

​Delete Location Level

​Location CRUD Operations

​List Locations

​Get Location by ID

​Create Location

​Update Location

​Delete Locations

​Location Groups

​List Location Groups

​Create Location Group

​Update Location Group

​Delete Location Group

​Common Workflows

​Setting Up a Multi-Site Organization

​Syncing Locations from External System

​Best Practices

​Related Guides

Overview

Key Concepts

Location Levels

Location Hierarchies

Location Level Operations

List Location Levels

Create Location Level

Update Location Level

Batch Update Location Levels

Delete Location Level

Location CRUD Operations

List Locations

Get Location by ID

Create Location

Update Location

Delete Locations

Location Groups

List Location Groups

Create Location Group

Update Location Group

Delete Location Group

Common Workflows

Setting Up a Multi-Site Organization

Syncing Locations from External System

Best Practices

Related Guides