Skip to main content

​
Overview

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

​
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.
PropertyDescription
idUnique identifier (UUID)
nameOrganization name
timezoneDefault timezone
statusActive or Inactive
Key Points:
  • All API requests require a workspace-id header
  • Users can belong to multiple workspaces
  • Data is isolated between workspaces

​
Users & Roles

​
User

A User represents a person who can access the platform.
PropertyDescription
idUnique identifier (UUID)
firstNameFirst name
lastNameLast name
emailIdEmail address (unique)
statusActive, Pending, or Inactive

​
WorkspaceUser

A WorkspaceUser represents a user’s membership in a specific workspace.
PropertyDescription
UserIdReference to the user
WorkspaceIdReference to the workspace
RoleIdUser’s role in this workspace
statusActive, Pending, or Inactive
isAdminWhether user has admin privileges

​
Role

A Role defines permissions for users within a workspace.
RoleDescription
OwnerFull access, can delete workspace
AdminFull access except workspace deletion
Full UserStandard access to all features
Basic UserLimited access based on permissions
RequesterCan 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.
PropertyDescription
idUnique identifier (UUID)
nameLocation name
ParentIdParent location (for hierarchy)
LevelIdLocation level (Country, Region, Site, etc.)
timezoneLocation-specific timezone
addressPhysical 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

​
Templates (Checklists)

A Template (also called Checklist) is a blueprint for inspections, audits, or forms.
PropertyDescription
idUnique identifier (UUID)
nameTemplate name
descriptionTemplate description
isPublishedWhether template is available for use
isScoringWhether 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:
TypeDescription
textFree text response
numberNumeric input
dropdownSingle selection from options
multipleChoiceMultiple selections
passFailPass/Fail/NA response
checkboxYes/No checkbox
dateDate picker
dateTimeDate and time picker
photoImage capture
signatureSignature capture
temperatureTemperature reading

​
Submissions

A Submission (also called ChecklistLog) is a completed instance of a template.
PropertyDescription
idUnique identifier (UUID)
ChecklistIdReference to the template
statusDraft, Submitted, Approved, Rejected
progressCompletion percentage
totalScoreMaximum possible score
achievedScoreActual score achieved

​
Submission Lifecycle

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

​
Submission Items

Each submission contains responses to template items:
PropertyDescription
ChecklistItemIdReference to the template item
answersResponse value(s)
scorePoints earned (if scoring enabled)
attachmentsPhotos, files attached
completedAtWhen item was answered

​
Tasks

A Task represents a work item or to-do.
PropertyDescription
idUnique identifier (UUID)
titleTask title
descriptionTask details
taskStatusOpen, InProgress, Completed, Paused
priorityHigh, Medium, Low
dueDateWhen task is due
recurringTaskWhether task repeats

​
Task Types

TypeDescription
One-offSingle task with due date
RecurringRepeats daily, weekly, or monthly
Work OrderRequest-based task
Corrective ActionAuto-created from failed inspection items

​
Task Assignees

Tasks can be assigned to:
  • Individual users
  • Teams
  • Roles

​
Projects

A Project groups related tasks together.
PropertyDescription
idUnique identifier (UUID)
titleProject name
stateDraft, Active, Paused, Completed
isSchedulesProjectContains 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

Start managing users

Templates API

Work with inspection templates

Submissions API

Manage completed inspections