Location Members

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

Feature Required: Location member management requires the ADVANCED_LOCATION_BASED_ASSIGNMENT feature to be enabled for your workspace.

List Location Members

Retrieve all users assigned to a specific location.

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}"

Response:

{
  "status": "success",
  "code": 200,
  "data": [
    {
      "id": "user-uuid-1",
      "fullName": "John Smith",
      "email": "[email protected]",
      "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": "[email protected]",
      "photo": null,
      "RoleId": "role-uuid-2",
      "Role": {
        "id": "role-uuid-2",
        "title": "Technician"
      }
    }
  ]
}

Add Member to Location

Assign a single user to a location.

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"
  }'

Request Body:

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

Response:

{
  "status": "success",
  "code": 200,
  "message": "Member added to location successfully"
}

Permissions Required: CAN_ACCESS_LOCATIONS AND CAN_EDIT_LOCATIONS

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

Replace All Location Members

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

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"]
  }'

Request Body:

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

Response:

{
  "status": "success",
  "code": 200,
  "message": "Location members updated successfully"
}

This operation replaces ALL existing members. Users not in the memberIds array will be removed from the location.

Remove Member from Location

Remove a user from a specific location.

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}"

Path Parameters:

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

Response:

{
  "status": "success",
  "code": 200,
  "message": "Member removed from location successfully"
}

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.

Update User’s Locations

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

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"
  }'

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:

{
  "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" }
    ]
  }
}

Permissions Required: CAN_ACCESS_LOCATIONS AND CAN_EDIT_LOCATIONS

Assign Members During Location Creation

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

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"]
      }
    ]
  }'

Common Workflows

Onboarding a New Employee to Locations

Complete Example:

# Step 1: Create user (see User Lifecycle guide)
USER_ID=$(curl -X POST ".../users" -d '{"email": "[email protected]", ...}' | 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

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

# 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

# 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

Inheritance behavior depends on your workspace configuration. Contact support for custom location access rules.

Best Practices

Always set a default location

Every user with location assignments should have a defaultLocationId. This determines their initial view and default task routing.

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.

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.

Audit location assignments regularly

Periodically review location assignments to ensure departed employees are removed and transfers are reflected.

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.

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

Location Hierarchy - Set up locations and levels
User Lifecycle - Create and manage users
Team Management - Organize users into teams

Getting Started

Workflows

Integrations

Overview

List Location Members

Add Member to Location

Replace All Location Members

Remove Member from Location

Update User’s Locations

Assign Members During Location Creation

Common Workflows

Onboarding a New Employee to Locations

Transferring an Employee to a New Location

Bulk Assign Team to Location

Syncing Location Assignments from HR System

Location-Based Access Control

Hierarchy Inheritance

Best Practices

Error Handling

Getting Started

Workflows

Integrations

​Overview

​List Location Members

​Add Member to Location

​Replace All Location Members

​Remove Member from Location

​Update User’s Locations

​Assign Members During Location Creation

​Common Workflows

​Onboarding a New Employee to Locations

​Transferring an Employee to a New Location

​Bulk Assign Team to Location

​Syncing Location Assignments from HR System

​Location-Based Access Control

​Hierarchy Inheritance

​Best Practices

​Error Handling

​Related Guides

Overview

List Location Members

Add Member to Location

Replace All Location Members

Remove Member from Location

Update User’s Locations

Assign Members During Location Creation

Common Workflows

Onboarding a New Employee to Locations

Transferring an Employee to a New Location

Bulk Assign Team to Location

Syncing Location Assignments from HR System

Location-Based Access Control

Hierarchy Inheritance

Best Practices

Error Handling

Related Guides