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

> Assign users to locations for location-based access control and task routing

## Overview

Location member assignment enables location-based access control in Xenia. By assigning users to specific locations, you can:

* **Control visibility**: Users only see data for their assigned locations
* **Route tasks**: Automatically assign tasks to users at specific locations
* **Enable reporting**: Generate location-specific performance reports
* **Manage schedules**: Create location-based inspection schedules

<Info>
  **Feature Required:** Location member management requires the `ADVANCED_LOCATION_BASED_ASSIGNMENT` feature to be enabled for your workspace.
</Info>

***

## List Location Members

Retrieve all users assigned to a specific location.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/locations/{locationId}/members" \
    -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": "user-uuid-1",
      "fullName": "John Smith",
      "email": "john.smith@company.com",
      "photo": "https://storage.example.com/avatars/john.jpg",
      "RoleId": "role-uuid",
      "Role": {
        "id": "role-uuid",
        "title": "Site Manager"
      }
    },
    {
      "id": "user-uuid-2",
      "fullName": "Jane Doe",
      "email": "jane.doe@company.com",
      "photo": null,
      "RoleId": "role-uuid-2",
      "Role": {
        "id": "role-uuid-2",
        "title": "Technician"
      }
    }
  ]
}
```

***

## Add Member to Location

Assign a single user to a location.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/locations/{locationId}/members" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "memberId": "user-uuid"
    }'
  ```
</CodeGroup>

**Request Body:**

| Field      | Type   | Required | Description                    |
| ---------- | ------ | -------- | ------------------------------ |
| `memberId` | string | Yes      | User ID to add to the location |

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "message": "Member added to location successfully"
}
```

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

<Tip>
  Adding a user who is already a member of the location is a no-op (no error, no duplicate created).
</Tip>

***

## Replace All Location Members

Set the complete list of members for a location, replacing any existing assignments.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/locations/{locationId}/members" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "memberIds": ["user-uuid-1", "user-uuid-2", "user-uuid-3"]
    }'
  ```
</CodeGroup>

**Request Body:**

| Field       | Type      | Required | Description                                 |
| ----------- | --------- | -------- | ------------------------------------------- |
| `memberIds` | string\[] | Yes      | Array of user IDs to assign to the location |

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "message": "Location members updated successfully"
}
```

<Warning>
  This operation replaces ALL existing members. Users not in the `memberIds` array will be removed from the location.
</Warning>

***

## Remove Member from Location

Remove a user from a specific location.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/locations/{locationId}/members/{memberId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

**Path Parameters:**

| Parameter    | Type | Description                    |
| ------------ | ---- | ------------------------------ |
| `locationId` | UUID | Location to remove member from |
| `memberId`   | UUID | User ID to remove              |

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "message": "Member removed from location successfully"
}
```

<Warning>
  You cannot remove a user from their **default location**. Update their default location first, or use the "Update User's Locations" endpoint to change both at once.
</Warning>

***

## Update User's Locations

Update which locations a user is assigned to and optionally set their default location.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/users/{memberId}/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 '{
      "locations": ["location-uuid-1", "location-uuid-2", "location-uuid-3"],
      "defaultLocationId": "location-uuid-1"
    }'
  ```
</CodeGroup>

**Request Body:**

| Field               | Type      | Required | Description                                            |
| ------------------- | --------- | -------- | ------------------------------------------------------ |
| `locations`         | string\[] | No       | Array of location IDs to assign to the user            |
| `defaultLocationId` | UUID      | No       | User's default location (must be in `locations` array) |

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "user-uuid",
    "fullName": "John Smith",
    "defaultLocationId": "location-uuid-1",
    "locations": [
      { "id": "location-uuid-1", "name": "NYC Office" },
      { "id": "location-uuid-2", "name": "Chicago Office" },
      { "id": "location-uuid-3", "name": "LA Office" }
    ]
  }
}
```

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

***

## Assign Members During Location Creation

You can assign members when creating a location by including `memberIds` in the hierarchy configuration.

<CodeGroup>
  ```bash cURL 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": "New Site",
      "description": "Recently opened location",
      "hierarchies": [
        {
          "hierarchyId": "hierarchy-uuid",
          "ParentId": "parent-location-uuid",
          "LevelId": "site-level-uuid",
          "memberIds": ["user-uuid-1", "user-uuid-2", "user-uuid-3"]
        }
      ]
    }'
  ```
</CodeGroup>

***

## Common Workflows

### Onboarding a New Employee to Locations

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

    Client->>API: 1. Create user
    API-->>Client: User created (user-uuid)

    Client->>API: 2. Get available locations
    API-->>Client: Location list

    Client->>API: 3. Assign user to locations
    Note right of Client: PUT /users/{userId}/locations
    API-->>Client: User assigned

    Client->>API: 4. Set default location
    Note right of Client: Include defaultLocationId
    API-->>Client: Default set
```

**Complete Example:**

```bash theme={null}
# Step 1: Create user (see User Lifecycle guide)
USER_ID=$(curl -X POST ".../users" -d '{"email": "new.hire@company.com", ...}' | jq -r '.data.id')

# Step 2: Assign to multiple locations with default
curl -X PUT ".../users/${USER_ID}/locations" \
  -d '{
    "locations": ["nyc-office-uuid", "chicago-office-uuid"],
    "defaultLocationId": "nyc-office-uuid"
  }'
```

### Transferring an Employee to a New Location

```bash theme={null}
# Get current locations
curl -X GET ".../users/{userId}"

# Update locations (remove old, add new)
curl -X PUT ".../users/{userId}/locations" \
  -d '{
    "locations": ["new-location-uuid"],
    "defaultLocationId": "new-location-uuid"
  }'
```

### Bulk Assign Team to Location

When opening a new location or restructuring, assign multiple users at once:

```bash theme={null}
# Replace all members at a location
curl -X PUT ".../locations/{locationId}/members" \
  -d '{
    "memberIds": [
      "manager-uuid",
      "tech-1-uuid",
      "tech-2-uuid",
      "tech-3-uuid",
      "receptionist-uuid"
    ]
  }'
```

### Syncing Location Assignments from HR System

```bash theme={null}
# For each employee in HR system:
for employee in hr_employees:
    # Map HR location codes to Xenia location IDs
    xenia_locations = map_hr_to_xenia(employee.locations)

    # Update user's location assignments
    curl -X PUT ".../users/{employee.xenia_id}/locations" \
      -d "{
        \"locations\": ${xenia_locations},
        \"defaultLocationId\": \"${employee.primary_location}\"
      }"
```

***

## Location-Based Access Control

When users are assigned to locations, Xenia automatically enforces location-based visibility:

| Feature           | Behavior                                          |
| ----------------- | ------------------------------------------------- |
| **Tasks**         | Users see tasks at their assigned locations       |
| **Submissions**   | Users can complete inspections at their locations |
| **Reporting**     | Reports filter to user's location scope           |
| **Notifications** | Location-specific alerts sent to assigned users   |

### Hierarchy Inheritance

Location assignments can inherit up or down the hierarchy based on configuration:

* **Parent access**: User assigned to "North America" may see all sub-locations
* **Site-specific**: User assigned to "NYC Office" only sees that site
* **Room-level**: User assigned to specific rooms sees only those rooms

<Note>
  Inheritance behavior depends on your workspace configuration. Contact support for custom location access rules.
</Note>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Always set a default location">
    Every user with location assignments should have a `defaultLocationId`. This determines their initial view and default task routing.
  </Accordion>

  <Accordion title="Use batch operations for bulk changes">
    When restructuring or onboarding multiple users, use `PUT /locations/{id}/members` to set all members at once rather than individual adds/removes.
  </Accordion>

  <Accordion title="Coordinate with role permissions">
    Location-based access works alongside role permissions. A user needs both the right role permissions AND location assignment to access features.
  </Accordion>

  <Accordion title="Audit location assignments regularly">
    Periodically review location assignments to ensure departed employees are removed and transfers are reflected.
  </Accordion>

  <Accordion title="Consider multi-location workers">
    Some employees (regional managers, traveling technicians) need access to multiple locations. Assign all relevant locations and set their most common site as default.
  </Accordion>
</AccordionGroup>

***

## Error Handling

| Error Code | Message                                    | Resolution                                                       |
| ---------- | ------------------------------------------ | ---------------------------------------------------------------- |
| 400        | "Cannot remove user from default location" | Update default location first or use `PUT /users/{id}/locations` |
| 403        | "Feature not enabled"                      | Contact admin to enable `ADVANCED_LOCATION_BASED_ASSIGNMENT`     |
| 404        | "Location not found"                       | Verify location ID exists and is not deleted                     |
| 404        | "User not found"                           | Verify user ID exists in the workspace                           |

***

## Related Guides

* [Location Hierarchy](/guides/workflows/location-hierarchy) - Set up locations and levels
* [User Lifecycle](/guides/workflows/user-lifecycle) - Create and manage users
* [Team Management](/guides/workflows/team-management) - Organize users into teams