# PERS Terminology Dictionary

This dictionary explains key concepts, entities, and processes within the PERS platform.

## 1. Connect - System Setup & Architecture

First, we set up all of the key components you need for your system to operate.

**Tenant:** You and your organization's program instance. Each tenant operates independently with complete data isolation and custom configuration within the PERS multi-tenant architecture.

**User:** Your customers who engage with the tokenization system through your front-end applications, mobile apps, or partner interfaces.

**Admin:** Administrative users with elevated permissions to manage tenant-level operations, configurations, and system oversight.

**Platform:** A third-party platform, software, or system that integrates with your PERS operations. Examples include CRM systems, booking platforms, EPOS systems, or e-commerce platforms.

**Integration:** The seamless communication layer between your existing platforms and PERS. Compatible with any system that supports REST APIs, webhooks, or standard authentication protocols.

**API:** RESTful application programming interfaces that enable secure communication and data exchange between PERS and external systems.

**Project Key (Context ID):** A Public unique identifier for your Tenant/Project context. It ensures that your requests are routed to the correct isolated environment. Required for all API calls but does not provide authentication.

**Trigger Source:** A specific activation point that can initiate campaign flows. Trigger sources are reusable, agnostic entities that represent how campaigns can be triggered:

- **QR Code:** Physical or digital QR codes at specific locations (e.g., store entrance, product display)
- **NFC Tag:** Near-field communication tags embedded in physical touchpoints
- **API Webhook:** Integration endpoints for external system events (e.g., purchase completion, booking confirmation)
- **GPS Geofence:** Pure location-based triggers activated when users enter defined geographic areas
- **Transaction:** Blockchain transaction events that trigger campaign flows


Each trigger source can be assigned to multiple campaigns and supports type-specific configuration through metadata. **All trigger source types support optional geographic coordinates** (`coordsLatitude`, `coordsLongitude`) to enable location-based proximity validation - for example, a QR code that only works when scanned within 50 meters of its physical location, or an API webhook that validates the event occurred at a specific business location. Location coordinates can be set directly on the trigger source or inherited from an associated business location.

**Campaign Trigger:** The business rules and conditions that determine when and how a trigger source activates a campaign. Campaign triggers define:

- Activation frequency limits (max per day, max per user, cooldown periods)
- Geographic proximity requirements (`maxGeoDistanceInMeters` for location-based validation)
- Required user information and custom conditions
- Completion thresholds and multipliers
- How multiple trigger sources combine (`sourceLogic`: ANY or ALL)


The separation between trigger sources (physical/technical activation points) and campaign triggers (business rules) allows flexible reuse of trigger sources across different campaigns with varying constraints.

**Business:** A real-world touchpoint or partner location within your PERS ecosystem. Examples include retail stores, restaurants, service providers, or any physical/digital location where users interact with your loyalty program. Business entities include geographic coordinates (`coordsLatitude`, `coordsLongitude`) that serve as fallback locations for geofence trigger sources when trigger-specific coordinates are not provided.

## 2. Create - Loyalty Program Design & Configuration

Define the actions you want to encourage and the rewards you'll offer by creating the strategic frameworks for user engagement.

**Token:** PERS operates with flexible token types designed to optimize your loyalty strategy. The platform supports various token categories:

- **Credits/Points:** Basic digital currency tokens for standard transactions and accumulation
- **Rewards:** Tokens representing real-world experiences, products, or services (e.g., free beverages, exclusive experiences, merchandise)
- **Status Tokens:** Digital representations of achievements, memberships, or special recognition levels


**Campaign:** Strategic marketing initiatives that define available tokens, participation requirements, and trigger conditions for user engagement. Campaigns can be:

- **Public Campaigns:** Discoverable by all users without authentication
- **Targeted Campaigns:** Specific to user segments or business partners
- **Time-Limited Campaigns:** Active for defined periods with start/end dates
- **Event-Based Campaigns:** Triggered by specific user actions or external events via trigger sources


**Campaign Tags:** Organizational labels that categorize campaigns for easier discovery and management across your loyalty program catalog.

**Campaign Tokens:** Specific reward configurations linking token types and amounts to campaign participation outcomes.

**Campaign Triggers:** Business rule configurations that define when and how campaigns activate for users. Each campaign trigger includes:

- **Trigger Conditions:** Custom validation rules based on user metadata or context
- **Geographic Constraints:** Location-based requirements using `maxGeoDistanceInMeters` to validate user proximity to trigger source or business coordinates
- **Frequency Limits:** Control mechanisms for claim rates (per user, per day, cooldown periods, completion thresholds)
- **Source Logic:** Defines how multiple trigger sources combine (ANY = any source activates, ALL = all sources required)


Campaign triggers connect to trigger sources (physical/technical activation points) while maintaining separation of business rules from infrastructure concerns.

**Campaign Engagements:** B2B relationship management features enabling multi-business collaboration and cross-partner reward programs.

**Redemption:** Exchange mechanisms that define how users can convert accumulated tokens into rewards, products, or services. Redemptions support complex rules including exchange rates, eligibility requirements, and partner network availability.

## 3. Reward - Active Program Operations & User Engagement

With your loyalty system live and campaigns active, all user engagement is automatically tracked and rewarded within PERS.

**Balance:** Real-time tracking of token holdings across all user accounts, supporting multiple token types simultaneously with instant updates from all transaction sources.

**Wallet:** Digital token storage where earned rewards are held. Each entity (users, businesses, tenants) maintains an isolated wallet with security controls.

**Transaction:** Comprehensive record-keeping system capturing all token movements and operations. Transaction types include:

- **Mint:** Creation of new tokens and addition to user accounts (reward distribution)
- **Transfer:** Secure movement of tokens between wallets (peer-to-peer or business-to-user)
- **Burn:** Permanent removal of tokens from circulation (typically following redemption or expiration)


**Claim:** User participation in reward programs. Claim processing supports multiple access levels:

- **USER Claims:** Direct customer reward claims through authenticated user interfaces
- **BUSINESS Claims:** B2B reward processing with business context attribution
- **SYSTEM Claims:** Automated claims triggered by integrated platforms and APIs
- **ADMIN Claims:** Administrative oversight and manual claim processing for special circumstances


**Purchase:** Secure payment processing system enabling users to top-up account balances through various payment methods, supporting premium features and additional token acquisition.

**File Management:** Secure asset storage and delivery system for campaign images, user avatars, and program-related media with role-based access controls.

**Authentication & Authorization:** Multi-level security supporting USER, BUSINESS, ADMIN, and SYSTEM access levels with JWT-based authentication.

## Technical Infrastructure Terms

**Blockchain Integration:** Multi-chain support for token operations including network configuration, smart contract deployment, and cross-chain compatibility.

**Web3 Chains:** Blockchain network management supporting multiple networks simultaneously with real-time status monitoring and gas optimization.

**Smart Contracts:** Automated blockchain-based contracts managing token operations with upgrade capabilities and event monitoring.

**Webhooks:** Real-time event notification system enabling integration with external platforms through secure callback mechanisms.

**JWKS (JSON Web Key Set):** Security infrastructure providing public keys for JWT token verification across the platform ecosystem.

**All of this can be created and managed within your PERS dashboard and through RESTful APIs.**