Core Concepts

Overview

Xenia is a multi-tenant operations management platform. Understanding its core entities will help you build effective integrations.

This page explains the platform’s data model. The public API is read- and reporting-focused: you can read users, locations, roles, tasks, and submissions, and pull analytics/exports. Creating and editing templates, tasks, projects, and submissions happens in the Xenia app — those write operations are not part of the API-key surface. See the API Reference for exactly what a client key can call.

Entity Hierarchy

Workspace (Organization)
├── Users (People)
│   └── WorkspaceUser (Membership with Role)
├── Roles (Permissions)
├── Locations (Physical Sites)
│   └── Location Members
├── Templates (Inspection Blueprints)
│   ├── Sections
│   └── Items (Questions)
├── Submissions (Completed Inspections)
│   └── Item Responses (Answers)
├── Tasks (Work Items)
│   └── Assignees
└── Projects (Task Groups)

Workspace

A Workspace is the top-level container that represents your organization. All data is scoped to a workspace.

Property	Description
`id`	Unique identifier (UUID)
`name`	Organization name
`timezone`	Default timezone
`status`	Active or Inactive

Key Points:

The workspace is derived automatically from your client key — you do not send a workspace-id header (only supply a workspace ID where an endpoint path contains {workspaceId})
Users can belong to multiple workspaces
Data is isolated between workspaces

Users & Roles

User

A User represents a person who can access the platform.

Property	Description
`id`	Unique identifier (UUID)
`firstName`	First name
`lastName`	Last name
`emailId`	Email address (unique)
`status`	Active, Pending, or Inactive

WorkspaceUser

A WorkspaceUser represents a user’s membership in a specific workspace.

Property	Description
`UserId`	Reference to the user
`WorkspaceId`	Reference to the workspace
`RoleId`	User’s role in this workspace
`status`	Active, Pending, or Inactive
`isAdmin`	Whether user has admin privileges

Role

A Role defines permissions for users within a workspace.

Role	Description
Owner	Full access, can delete workspace
Admin	Full access except workspace deletion
Full User	Standard access to all features
Basic User	Limited access based on permissions
Requester	Can only create requests

Role Permissions control what users can do:

CAN_MANAGE_USERS - Create, edit, delete users
CAN_MANAGE_ROLES - Create and modify roles
CAN_MANAGE_TASKS - Create and assign tasks
CAN_MANAGE_CHECKLIST - Create and edit templates

Locations

Locations represent physical sites in your organization, organized in a hierarchy.

Property	Description
`id`	Unique identifier (UUID)
`name`	Location name
`ParentId`	Parent location (for hierarchy)
`LevelId`	Location level (Country, Region, Site, etc.)
`timezone`	Location-specific timezone
`address`	Physical address

Location Levels

Location levels define your organizational hierarchy:

Country (Level 1)
└── Region (Level 2)
    └── City (Level 3)
        └── Store (Level 4 - Site)

Location Members

Users are assigned to locations. This determines:

Which locations they can access
Which tasks they receive
Which submissions they can view

Replace a single user’s memberships with Replace User Locations.

Location Attributes

Location attributes are typed properties you define once and then set per location — Region, Drive Thru Lanes, Remodel Date, Has Freezer. Six types are available: single_select, multi_select, number, boolean, text, and date. Attributes are how you model a dimension that changes over time or that you want to drive assignment from, without restructuring the hierarchy itself.

Keeping locations in sync from your own systems

The Enterprise Locations endpoints let an IT system maintain this structure on a schedule instead of by hand. Every write is a bulk, idempotent upsert keyed by your own external_id, so re-running the same payload is safe:

Bulk Upsert Hierarchies — hierarchies and their levels
Bulk Upsert Locations — create and rename locations
Bulk Upsert Location Attributes — attribute definitions
Bulk Upsert Attribute Values — each location’s values
List Locations and List Location Attributes — reconciliation reads

Moving an existing location to a different parent (for example a store from one district to another) is not supported by these endpoints — a placement change on an existing location is rejected rather than applied. Re-parent in the Xenia UI, or model the changing dimension as a location attribute and update its value instead.

These endpoints require the Public API and Location Attributes features on your workspace.

Templates (Checklists)

A Template (also called Checklist) is a blueprint for inspections, audits, or forms.

Property	Description
`id`	Unique identifier (UUID)
`name`	Template name
`description`	Template description
`isPublished`	Whether template is available for use
`isScoring`	Whether scoring is enabled

Template Structure

Template
├── Section 1
│   ├── Item (Question) 1.1
│   ├── Item (Question) 1.2
│   └── Item (Question) 1.3
├── Section 2
│   ├── Item (Question) 2.1
│   └── Item (Question) 2.2
└── Section 3
    └── Item (Question) 3.1

Item Types

Templates contain various question types:

Type	Description
`text`	Free text response
`number`	Numeric input
`dropdown`	Single selection from options
`multipleChoice`	Multiple selections
`passFail`	Pass/Fail/NA response
`checkbox`	Yes/No checkbox
`date`	Date picker
`dateTime`	Date and time picker
`photo`	Image capture
`signature`	Signature capture
`temperature`	Temperature reading

Submissions

A Submission (also called ChecklistLog) is a completed instance of a template.

Property	Description
`id`	Unique identifier (UUID)
`ChecklistId`	Reference to the template
`status`	Draft, Submitted, Approved, Rejected
`progress`	Completion percentage
`totalScore`	Maximum possible score
`achievedScore`	Actual score achieved

Submission Lifecycle

Start      → Creates draft submission
Fill       → Answer questions (items)
Submit     → Mark as complete
Approve    → (Optional) Approval workflow
Export     → Generate PDF/Excel report

Submission Items

Each submission contains responses to template items:

Property	Description
`ChecklistItemId`	Reference to the template item
`answers`	Response value(s)
`score`	Points earned (if scoring enabled)
`attachments`	Photos, files attached
`completedAt`	When item was answered

Tasks

A Task represents a work item or to-do.

Property	Description
`id`	Unique identifier (UUID)
`title`	Task title
`description`	Task details
`taskStatus`	One of the stored values: `Open`, `In Progress`, `On Hold`, `Completed`, `Missed`, `Incomplete` (note the space in `In Progress`)
`priority`	High, Medium, Low
`dueDate`	When task is due
`recurringTask`	Whether task repeats

Task Types

Type	Description
One-off	Single task with due date
Recurring	Repeats daily, weekly, or monthly
Work Order	Request-based task
Corrective Action	Auto-created from failed inspection items

Task Assignees

Tasks can be assigned to:

Individual users
Teams
Roles

Projects

A Project groups related tasks together.

Property	Description
`id`	Unique identifier (UUID)
`title`	Project name
`state`	Draft, Active, Paused, Completed
`isSchedulesProject`	Contains recurring tasks

Use Cases:

Group daily opening/closing tasks
Organize seasonal maintenance schedules
Track multi-step projects

Entity Relationships

Next Steps

Error Handling

Learn to handle API errors gracefully

Users API

Read and manage users

Tasks API

Read tasks and work orders

Reporting API

Submission records and analytics

Getting Started

Workflows

Integrations

Overview

Entity Hierarchy

Workspace

Users & Roles

User

WorkspaceUser

Role

Locations

Location Levels

Location Members

Location Attributes

Keeping locations in sync from your own systems

Templates (Checklists)

Template Structure

Item Types

Submissions

Submission Lifecycle

Submission Items

Tasks

Task Types

Task Assignees

Projects

Entity Relationships

Next Steps

Error Handling

Users API

Tasks API

Reporting API

​Overview

​Entity Hierarchy

​Workspace

​Users & Roles

​User

​WorkspaceUser

​Role

​Locations

​Location Levels

​Location Members

​Location Attributes

​Keeping locations in sync from your own systems

​Templates (Checklists)

​Template Structure

​Item Types

​Submissions

​Submission Lifecycle

​Submission Items

​Tasks

​Task Types

​Task Assignees

​Projects

​Entity Relationships

​Next Steps

Error Handling

Users API

Tasks API

Reporting API

Overview

Entity Hierarchy

Workspace

Users & Roles

User

WorkspaceUser

Role

Locations

Location Levels

Location Members

Location Attributes

Keeping locations in sync from your own systems

Templates (Checklists)

Template Structure

Item Types

Submissions

Submission Lifecycle

Submission Items

Tasks

Task Types

Task Assignees

Projects

Entity Relationships

Next Steps