> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenia.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Location Hierarchy

> Manage location structures, levels, and hierarchies in your workspace

## 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.

<CodeGroup>
  ```bash cURL theme={null}
  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}"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

| 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:**

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

<Note>
  **Permission Required:** `CAN_MANAGE_LOCATIONS`
</Note>

### Update Location Level

Modify an existing location level.

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

### Batch Update Location Levels

Update multiple levels at once (useful for reordering).

<CodeGroup>
  ```bash cURL theme={null}
  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 }
      ]
    }'
  ```
</CodeGroup>

### Delete Location Level

Remove a location level from the hierarchy.

<CodeGroup>
  ```bash cURL theme={null}
  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}"
  ```
</CodeGroup>

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

***

## Location CRUD Operations

### List Locations

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

<CodeGroup>
  ```bash cURL (Tree Structure) theme={null}
  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}"
  ```

  ```bash cURL (Flat List) theme={null}
  curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/locations?notree=true" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```

  ```bash cURL (Sites Only) theme={null}
  curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/locations?onlySite=true" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

**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):**

```json theme={null}
{
  "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": []
            }
          ]
        }
      ]
    }
  ]
}
```

<Note>
  **Permission Required:** `CAN_ACCESS_LOCATIONS`
</Note>

### Get Location by ID

Retrieve details of a specific location.

<CodeGroup>
  ```bash cURL theme={null}
  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}"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "location-uuid",
    "name": "New York Office",
    "description": "NYC Headquarters",
    "address": "123 Main Street, New York, NY 10001",
    "email": "nyc@company.com",
    "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.

<CodeGroup>
  ```bash cURL (Simple) theme={null}
  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": "chicago@company.com",
      "latitude": 41.8781,
      "longitude": -87.6298,
      "isQREnable": true
    }'
  ```

  ```bash cURL (With Hierarchy Placement) theme={null}
  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",
      "hierarchies": [
        {
          "hierarchyId": "geo-hierarchy-uuid",
          "ParentId": "midwest-region-uuid",
          "LevelId": "site-level-uuid"
        }
      ]
    }'
  ```

  ```bash cURL (With Sublocations) theme={null}
  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",
      "Sublocations": {
        "Floor 1": {
          "Sublocations": {
            "Lobby": {},
            "Conference Room A": {},
            "Kitchen": {}
          }
        },
        "Floor 2": {
          "Sublocations": {
            "Open Office": {},
            "Meeting Room B": {}
          }
        }
      }
    }'
  ```
</CodeGroup>

**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 |

<Note>
  **Permissions Required:** `CAN_ACCESS_LOCATIONS` AND `CAN_CREATE_LOCATIONS`
</Note>

### Update Location

Modify an existing location.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

<Note>
  **Permissions Required:** `CAN_ACCESS_LOCATIONS` AND `CAN_EDIT_LOCATIONS`
</Note>

### Delete Locations

Soft delete one or more locations.

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```
</CodeGroup>

<Note>
  **Permissions Required:** `CAN_ACCESS_LOCATIONS` AND `CAN_DELETE_LOCATIONS`
</Note>

<Warning>
  Deleting a parent location will also delete all child locations in its subtree.
</Warning>

***

## 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

<CodeGroup>
  ```bash cURL theme={null}
  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}"
  ```

  ```bash cURL (With Search) theme={null}
  curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/location-groups?search=priority" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```
</CodeGroup>

<Note>
  **Permission Required:** `CAN_MANAGE_LOCATIONS`
</Note>

### Update Location Group

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```
</CodeGroup>

### Delete Location Group

<CodeGroup>
  ```bash cURL theme={null}
  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}"
  ```
</CodeGroup>

***

## Common Workflows

### Setting Up a Multi-Site Organization

```mermaid theme={null}
sequenceDiagram
    participant API as Xenia API
    participant Client as Your System

    Client->>API: 1. Create location levels
    Note right of Client: Region → Site → Floor → Room
    API-->>Client: Levels created

    Client->>API: 2. Create top-level locations
    Note right of Client: North America, Europe, Asia
    API-->>Client: Regions created

    Client->>API: 3. Create sites under regions
    Note right of Client: NYC, Chicago, London
    API-->>Client: Sites created

    Client->>API: 4. Create floors/rooms under sites
    Note right of Client: Floor 1, Floor 2, Lobby
    API-->>Client: Sub-locations created
```

**Step 1: Create Location Levels**

```bash theme={null}
# 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**

```bash theme={null}
# 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:

```bash theme={null}
# 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"
  }'
```

<Tip>
  Use `UniqueLocationId` to maintain a stable identifier for locations that exist in multiple hierarchies or external systems.
</Tip>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Plan your hierarchy before creating">
    Design your location levels and structure before importing data. Changing the hierarchy later requires moving locations and updating references.
  </Accordion>

  <Accordion title="Use meaningful level names">
    Choose level names that match your organization's terminology. Users will see these names throughout the application.
  </Accordion>

  <Accordion title="Mark operational sites correctly">
    Set `isSite: true` on the level that represents your primary operational locations. This affects filtering and reporting.
  </Accordion>

  <Accordion title="Leverage location groups">
    Use groups for cross-cutting concerns (priority tiers, operational schedules) that don't fit the physical hierarchy.
  </Accordion>

  <Accordion title="Include geographic data">
    Adding latitude/longitude enables map-based features and location-aware functionality.
  </Accordion>
</AccordionGroup>

***

## Related Guides

* [Location Members](/guides/workflows/location-members) - Assign users to locations
* [Asset Management](/guides/workflows/asset-management) - Manage assets at locations
* [Team Management](/guides/workflows/team-management) - Organize users into teams