# PERS API Documentation

## Welcome to PERS

**PERS (Phygital Experience Rewards System)** is a SaaS tokenization infrastructure that enables brands, companies, and destinations to measure, secure, and tokenize user interactions across both physical and digital touchpoints. Functioning primarily as a loyalty and rewards system, PERS is built on a blockchain-based, API-first, and technology-agnostic architecture, designed to integrate into existing platforms as a white-label solution.

## What is PERS?

PERS is a multi-tenant, cloud-native tokenization platform for the experience economy—spanning tourism, hospitality, culture, retail, and events. By unifying fragmented data into a single engagement layer, PERS enables organizations to:

- **Tokenize User Interactions** - Measure and secure interactions across physical and digital touchpoints
- **Increase Customer Retention** - Drive meaningful engagement through targeted reward campaigns
- **Generate Actionable Insights** - Transform every interaction into measurable value for data-driven decisions
- **Scale Partner Ecosystems** - Enable collaboration across partner networks with interoperable rewards
- **Enterprise-Grade Security** - Complete data isolation with blockchain-based transaction integrity
- **White-Label Integration** - RESTful APIs designed for seamless integration as a fully branded solution


## Platform Overview

PERS enables businesses to create loyalty programs that engage customers across multiple touchpoints. The platform supports token distribution, campaign participation, and cross-partner redemptions.

## Core Components

### **Multi-Tenant Architecture**

Each business operates as an independent tenant with complete data isolation and custom configuration capabilities.

### **Token System**

Token management supporting Credits, Rewards, and Status tokens:

- Token creation and distribution
- Real-time balance tracking
- Secure transfers between users
- Controlled token burning for deflationary mechanics


### **Campaign Management**

Sophisticated campaign system enabling businesses to create engaging reward experiences:

- **Core Campaigns** - Primary campaign creation and management
- **Campaign Tags** - Organization and categorization system
- **Campaign Tokens** - Reward configuration and distribution rules
- **Campaign Triggers** - Automated activation based on user actions
- **Campaign Engagements** - B2B partnership and collaboration features
- **Campaign Claims** - Secure reward distribution with audit trails


### **Transaction Processing**

Comprehensive transaction management with:

- Token minting and burning operations
- Secure peer-to-peer transfers
- Real-time balance updates
- Complete audit trails for compliance


### **Redemption System**

Flexible token exchange enabling:

- Conversion between different token types
- Reward catalog integration
- Partner ecosystem redemptions
- Custom exchange rules and rates


## Getting Started

### 1. **Authentication**

PERS supports multiple authentication methods:

- **JWT User Authentication** - For end-user operations
- **Admin Authentication** - For tenant administrative functions
- **System Integration** - For automated platform interactions


### 2. **Basic Workflow**

1. **Tenant Setup** - Configure your organization's loyalty program
2. **Token Configuration** - Define token types and rules
3. **Campaign Creation** - Build engaging reward campaigns
4. **User Participation** - Enable customers to earn and redeem tokens
5. **Analytics & Optimization** - Monitor performance and iterate


### 3. **Integration Patterns**

- **RESTful APIs** - Standard HTTP endpoints for all operations
- **Real-Time Events** - Webhook integration for event-driven architectures
- **Secure Authentication** - JWT-based security with role-based access control
- **Multi-Environment** - Support for testnet and mainnet deployments


## API Architecture

### **Resource-Based Design**

PERS follows RESTful principles with intuitive resource naming:

- `/campaigns` - Campaign management operations
- `/tokens` - Token system operations
- `/transactions` - Transaction processing
- `/users` - User account management
- `/businesses` - Partner ecosystem management


### **Security & Compliance**

- **Role-Based Access Control** - Fine-grained permissions system
- **Data Encryption** - End-to-end encryption for sensitive data
- **Audit Trails** - Complete transaction history for regulatory compliance
- **Multi-Tenant Isolation** - Secure data separation between organizations


### **Performance & Scalability**

- **Cloud-Native Architecture** - Built for high availability and scalability
- **Real-Time Processing** - Instant transaction confirmation and balance updates
- **CDN Integration** - Global content delivery for optimal performance
- **Optimized Queries** - Efficient database operations for large-scale deployments


## Use Cases

### **Retail Loyalty Programs**

Create point-based systems where customers earn tokens for purchases and redeem them for discounts or products.

### **Multi-Brand Partnerships**

Enable collaborative programs where customers can earn tokens from one business and redeem them with partners.

### **Event-Based Rewards**

Configure campaigns that automatically reward users for specific actions like social media engagement or product reviews.

### **Gamification Systems**

Build status-based programs with different token types representing levels, achievements, or exclusive access.

## Base URL

**Production**: `https://api.pers.ninja/v2`

## Next Steps

1. **Authentication Setup** - Configure your API access and security credentials
2. **Explore the API** - Browse the endpoint documentation to understand available operations
3. **Test Environment** - Use testnet campaigns to experiment with the platform
4. **Integration Planning** - Plan your loyalty program architecture and integration points
5. **Go Live** - Deploy your loyalty program and start engaging customers


## Support & Resources

- **API Reference** - Comprehensive endpoint documentation
- **Integration Guides** - Step-by-step implementation examples
- **Best Practices** - Recommendations for optimal platform usage
- **Developer Community** - Connect with other developers building on PERS


**Ready to build engaging loyalty experiences?** Start exploring our API endpoints to discover how PERS can transform your customer engagement strategy.