# PERS-api docs Version: 2.0.2 ## Servers ``` https://api.pers.ninja/v2 ``` ## Security ### tenantAdminJWT Type: http Scheme: bearer Bearer Format: JWT ### authUserJWT Type: http Scheme: bearer Bearer Format: JWT ### authAdminJWT Type: http Scheme: bearer Bearer Format: JWT ### projectKey Project API key Type: apiKey In: header Name: x-project-key ### businessApiKey Business API key Type: apiKey In: header Name: x-api-key ## Download OpenAPI description [PERS-api docs](https://docs.pers.ninja/_bundle/swagger.yaml) ## Tenants ## Tenant Management
Tenant management for multi-tenant PERS loyalty platform. Each tenant represents a business or organization running their own reward program with dedicated data isolation and configuration.
**Core Features:**
• **Multi-Tenant Architecture:** Complete data isolation between tenant organizations
• **Tenant Configuration:** Custom settings, branding, and program rules per tenant
• **Admin Dashboard Access:** Comprehensive management interface for tenant administrators
• **Data Security:** Highest level confidentiality and security per tenant environment
• **API Integration:** Seamless integration with existing business systems ### Create new tenant - [POST /tenants](https://docs.pers.ninja/swagger/tenants/tenantscontroller_createtenant.md): Create a new tenant (project) in the system. This is the initial setup step for new organizations. ### Update tenant configuration - [PUT /tenants](https://docs.pers.ninja/swagger/tenants/tenantscontroller_updatetenant.md): ADMIN: Update tenant information and settings ### Get public tenant information - [GET /tenants/public](https://docs.pers.ninja/swagger/tenants/tenantscontroller_getpublictenant.md): Retrieve public tenant information visible to all users ### Get client configuration - [GET /tenants/client-config](https://docs.pers.ninja/swagger/tenants/tenantscontroller_getclientconfig.md): Retrieve client-side configuration for the project ### Get login token - [GET /tenants/login-token](https://docs.pers.ninja/swagger/tenants/tenantscontroller_getlogintoken.md): Generate a login token for the project ### Create new API key - [POST /tenants/api-keys](https://docs.pers.ninja/swagger/tenants/tenantscontroller_createapikey.md): ADMIN: Create a new API key for the tenant. Store this key securely - it cannot be retrieved again. ### Create new JWT token - [POST /tenants/jwt-tokens](https://docs.pers.ninja/swagger/tenants/tenantscontroller_createjwttoken.md): ADMIN: Create a new JWT token for the tenant. Store this token securely - it cannot be retrieved again. ## Admins ## Administrative Management
Administrative user management for tenant administrators. Handles admin authentication, permissions, and tenant-level administrative operations with secure access controls.
**Admin Features:**
• **Admin Authentication:** Secure admin login and session management
• **Permission Management:** Role-based access control for administrative functions
• **Tenant Administration:** Full tenant configuration and management capabilities
• **Security Controls:** Enhanced security measures for administrative access
• **Multi-Level Access:** Support for different administrative privilege levels ### Get all admins - [GET /admins](https://docs.pers.ninja/swagger/admins/adminscontroller_getadmins.md): ADMIN: Retrieve all admins associated with the current tenant ### Create or update admin - [POST /admins](https://docs.pers.ninja/swagger/admins/adminscontroller_createorupdateadmin.md): ADMIN: Create a new admin or update an existing admin within the tenant scope ### Toggle admin-tenant association - [PUT /admins/{adminId}/tenant](https://docs.pers.ninja/swagger/admins/adminscontroller_toggleadmintenantassociation.md): ADMIN: Associate or disassociate the specified admin with the current tenant. This affects admin tenant access. ## Tokens ## Token Management System
Token system for PERS loyalty platform managing various token types including Credits, Rewards, and Status tokens. Provides comprehensive token lifecycle management from creation to redemption.
**Token Operations:**
• **Token Creation:** Define custom token types with specific properties and rules
• **Token Distribution:** Mint and distribute tokens to users through campaigns
• **Balance Management:** Track token balances across user accounts
• **Token Transfer:** Enable token transfers between users when configured
• **Token Burning:** Remove tokens from circulation for deflationary mechanics ![Token Module](https://s3.eu-west-1.amazonaws.com/pers.assets.prod/tenant/a0df6ebf-51cc-4c18-afcd-0de355c250dc_DemoApp_eXplorins/Documentation/Tokens_image.png) ### Get all token contracts - [GET /tokens](https://docs.pers.ninja/swagger/tokens/tokenscontroller_getalltokens.md): Retrieve all token contracts for the project. Only admins can access inactive tokens via ?active=false parameter. ### Create new token contract - [POST /tokens](https://docs.pers.ninja/swagger/tokens/tokenscontroller_createtoken.md): ADMIN: Create a new testnet token contract for the project. This can later be converted to mainnet. ### Get token by contract address - [GET /tokens/address/{contractAddress}](https://docs.pers.ninja/swagger/tokens/tokenscontroller_gettokenbyaddress.md): Retrieve token information by contract address ### Get active point token - [GET /tokens/points](https://docs.pers.ninja/swagger/tokens/tokenscontroller_getactivepointtoken.md): Retrieve the active point token contract for the project ### Get all reward tokens - [GET /tokens/rewards](https://docs.pers.ninja/swagger/tokens/tokenscontroller_getrewardtokens.md): Retrieve all reward token contracts (ERC1155 tokens). Only admins can access inactive tokens via ?active=false parameter. ### Get all stamp tokens - [GET /tokens/stamps](https://docs.pers.ninja/swagger/tokens/tokenscontroller_getstamptokens.md): Retrieve all stamp token contracts (ERC721 tokens). Only admins can access inactive tokens via ?active=false parameter. ### Get all token types - [GET /tokens/types](https://docs.pers.ninja/swagger/tokens/tokenscontroller_getalltokentypes.md): Retrieve all available token types for the project ### Create new token type - [POST /tokens/types](https://docs.pers.ninja/swagger/tokens/tokenscontroller_createtokentype.md): ADMIN: Create a new token type for the project ### Update token contract - [PUT /tokens/{id}](https://docs.pers.ninja/swagger/tokens/tokenscontroller_updatetoken.md): ADMIN: Update token contract information ### Toggle token active status - [PUT /tokens/{id}/status](https://docs.pers.ninja/swagger/tokens/tokenscontroller_toggletokenstatus.md): ADMIN: Toggle token active status to enable/disable usage ### Set mainnet contract address - [PUT /tokens/{id}/mainnet](https://docs.pers.ninja/swagger/tokens/tokenscontroller_setmainnetcontract.md): ADMIN: Associate mainnet contract address with existing testnet token ### Create token metadata - [POST /tokens/{id}/metadata](https://docs.pers.ninja/swagger/tokens/tokenscontroller_createtokenmetadata.md): ADMIN: Create metadata for a specific token contract ### Toggle token metadata status - [PUT /tokens/metadata/{id}/status](https://docs.pers.ninja/swagger/tokens/tokenscontroller_toggletokenmetadatastatus.md): ADMIN: Toggle token metadata active status ## Campaigns ## Core Campaign Management
Core campaign CRUD operations with intelligent access detection. Handles campaign lifecycle management including creation, updates, activation, and querying with role-based access control.
**Campaign Operations:**
• **Campaign Discovery:** Public browsing of active campaigns without authentication
• **Advanced Filtering:** Query campaigns by tags, status, and custom criteria
• **Lifecycle Management:** Full campaign CRUD with proper state transitions
• **Environment Control:** Toggle campaigns between testnet and mainnet modes
• **Access Intelligence:** Automatic privilege detection for appropriate data exposure ![Campaign Module](https://s3.eu-west-1.amazonaws.com/pers.assets.prod/tenant/a0df6ebf-51cc-4c18-afcd-0de355c250dc_DemoApp_eXplorins/Documentation/Campaign_image.png) ### Get campaigns (Intelligent Access) - [GET /campaigns](https://docs.pers.ninja/swagger/campaigns/campaignscontroller_getcampaigns.md): Intelligent endpoint that adapts based on authentication: Public users get active campaigns with filtering, Admin users get all campaigns with full filtering. Replaces GET /campaign and GET /campaign/admin ### Create campaign (Admin) - [POST /campaigns](https://docs.pers.ninja/swagger/campaigns/campaignscontroller_createcampaign.md): Create a new campaign. Admin-only operation. Replaces POST /campaign/admin/ ### Get campaign by ID - [GET /campaigns/{id}](https://docs.pers.ninja/swagger/campaigns/campaignscontroller_getcampaignbyid.md): Get single campaign details by ID. Available to public with project key. Replaces GET /campaign/{id} ### Update campaign (Admin) - [PUT /campaigns/{id}](https://docs.pers.ninja/swagger/campaigns/campaignscontroller_updatecampaign.md): Update an existing campaign. Admin-only operation. Replaces PUT /campaign/admin/{id} ### Delete campaign (Admin) - [DELETE /campaigns/{id}](https://docs.pers.ninja/swagger/campaigns/campaignscontroller_deletecampaign.md): Delete an existing campaign. Admin-only operation. Replaces DELETE /campaign/admin/{id} ### Toggle campaign status (Admin) - [PUT /campaigns/{id}/status](https://docs.pers.ninja/swagger/campaigns/campaignscontroller_togglecampaignstatus.md): Toggle campaign active/inactive status. Admin-only operation. Replaces PUT /campaign/admin/{id}/activate ### Toggle campaign environment (Admin) - [PUT /campaigns/{id}/environment](https://docs.pers.ninja/swagger/campaigns/campaignscontroller_togglecampaignenvironment.md): Toggle campaign between testnet and mainnet environment. Admin-only operation. Replaces PUT /campaign/admin/{id}/environment ## Campaign Tags ## Campaign Organization System
Campaign tagging system for organization and categorization. Enables efficient campaign discovery through tag-based filtering and provides comprehensive tag management.
**Tag Management:**
• **Tag Discovery:** Browse all unique tags across campaign catalog
• **Campaign Tagging:** Associate multiple descriptive tags with campaigns
• **Tag-Based Filtering:** Enhanced campaign search and discovery via tags
• **Tag Administration:** Complete tag CRUD operations for administrators
• **Organization Tools:** Categorize campaigns by business criteria and themes ### Get all unique campaign tags (Admin) - [GET /campaign-tags](https://docs.pers.ninja/swagger/campaign-tags/campaigntagscontroller_getalluniquetags.md): Get all unique tags used across all campaigns. Admin-only operation for tag management. Replaces GET /campaign/tags ### Update campaign tags (Admin) - [PUT /campaign-tags/{id}](https://docs.pers.ninja/swagger/campaign-tags/campaigntagscontroller_updatecampaigntags.md): Replace all tags for a campaign with new tag list. Admin-only operation. Replaces PUT /campaign/admin/{id}/tags ### Add tags to campaign (Admin) - [POST /campaign-tags/{id}](https://docs.pers.ninja/swagger/campaign-tags/campaigntagscontroller_addtagstocampaign.md): Add new tags to existing campaign tags without removing existing ones. Admin-only operation. Replaces POST /campaign/admin/{id}/tags ### Remove tag from campaign (Admin) - [DELETE /campaign-tags/{id}/{tag}](https://docs.pers.ninja/swagger/campaign-tags/campaigntagscontroller_removetagfromcampaign.md): Remove a specific tag from campaign while preserving other tags. Admin-only operation. Replaces DELETE /campaign/admin/{id}/tags/{tag} ## Campaign Tokens ## Campaign Reward Configuration
Token unit management for campaign reward distribution. Defines specific token rewards that users receive when campaign participation conditions are met.
**Reward Configuration:**
• **Token Association:** Link specific token types and amounts to campaigns
• **Reward Rules:** Define token distribution rules and conditions
• **Multi-Token Support:** Configure multiple token types per campaign
• **Reward Calculation:** Set fixed or variable token amounts based on actions
• **Distribution Management:** Control how and when tokens are distributed to users ### Create campaign token unit (Admin) - [POST /campaign-tokens/{id}](https://docs.pers.ninja/swagger/campaign-tokens/campaigntokenscontroller_createcampaigntokenunit.md): Add a new token unit to campaign for reward distribution. Admin-only operation. Replaces POST /campaign/admin/{id}/token-units ### Update campaign token unit (Admin) - [PUT /campaign-tokens/{id}/{tokenUnitId}](https://docs.pers.ninja/swagger/campaign-tokens/campaigntokenscontroller_updatecampaigntokenunit.md): Update an existing token unit in campaign. Admin-only operation. Replaces PUT /campaign/admin/{id}/token-units/{tokenUnitId} ### Remove campaign token unit (Admin) - [DELETE /campaign-tokens/{id}/{tokenUnitId}](https://docs.pers.ninja/swagger/campaign-tokens/campaigntokenscontroller_removecampaigntokenunit.md): Remove a token unit from campaign. Admin-only operation. Replaces DELETE /campaign/admin/{id}/token-units/{tokenUnitId} ## Campaign Triggers ## Campaign Activation System
Campaign trigger system managing activation rules and eligibility conditions. Defines when and how campaigns activate including complex condition management for sophisticated campaign logic.
**Trigger Features:**
• **Trigger Catalog:** Public browsing of available campaign activation triggers
• **Condition Management:** Create complex trigger conditions with multiple criteria
• **Campaign Assignment:** Link triggers to campaigns for automated activation
• **Eligibility Rules:** Define sophisticated user participation requirements
• **Event-Based Activation:** Trigger campaigns based on user actions and external events ### Get all triggers (Public Catalog) - [GET /campaign-triggers](https://docs.pers.ninja/swagger/campaign-triggers/campaigntriggerscontroller_getalltriggers.md): Get all available triggers for campaign configuration. Public access for catalog browsing. Replaces GET /campaign/trigger/all ### Create campaign trigger (Admin) - [POST /campaign-triggers](https://docs.pers.ninja/swagger/campaign-triggers/campaigntriggerscontroller_createcampaigntrigger.md): Create a new campaign trigger for use in campaigns. Admin-only operation. Replaces POST /campaign/admin/trigger ### Update campaign trigger (Admin) - [PUT /campaign-triggers/{id}](https://docs.pers.ninja/swagger/campaign-triggers/campaigntriggerscontroller_updatecampaigntrigger.md): Update an existing campaign trigger. Admin-only operation. Replaces PUT /campaign/admin/trigger/{id} ### Delete campaign trigger (Admin) - [DELETE /campaign-triggers/{id}](https://docs.pers.ninja/swagger/campaign-triggers/campaigntriggerscontroller_deletecampaigntrigger.md): Delete an existing campaign trigger. Admin-only operation. Replaces DELETE /campaign/admin/trigger/{id} ### Assign trigger to campaign (Admin) - [PUT /campaign-triggers/campaigns/{id}/trigger/{triggerId}](https://docs.pers.ninja/swagger/campaign-triggers/campaigntriggerscontroller_assigntriggertocampaign.md): Assign a specific trigger to campaign for activation conditions. Admin-only operation. Replaces PUT /campaign/admin/{id}/trigger/{triggerId} ### Create trigger condition (Admin) - [POST /campaign-triggers/conditions](https://docs.pers.ninja/swagger/campaign-triggers/campaigntriggerscontroller_createtriggercondition.md): Create a new trigger condition for use in campaign triggers. Admin-only operation. Replaces POST /campaign/admin/trigger-condition ### Update trigger condition (Admin) - [PUT /campaign-triggers/conditions/{id}](https://docs.pers.ninja/swagger/campaign-triggers/campaigntriggerscontroller_updatetriggercondition.md): Update an existing trigger condition. Admin-only operation. Replaces PUT /campaign/admin/trigger-condition/{id} ### Toggle condition in trigger (Admin) - [PUT /campaign-triggers/{triggerId}/conditions/{conditionId}](https://docs.pers.ninja/swagger/campaign-triggers/campaigntriggerscontroller_toggleconditionintrigger.md): Add or remove a condition from a trigger (toggle relationship). Admin-only operation. Replaces PUT /campaign/admin/trigger/{triggerId}/condition/{conditionId} ## Campaign Engagements ## Business Relationship Management
B2B engagement management for multi-business campaign relationships. Handles business partnerships and enterprise-level campaign participation in complex loyalty ecosystems.
**B2B Features:**
• **Partner Integration:** Manage business-to-business campaign relationships
• **Enterprise Programs:** Support complex multi-business loyalty initiatives
• **Engagement Tracking:** Monitor business participation and performance metrics
• **Partnership Management:** Configure B2B reward sharing and attribution
• **Cross-Business Rewards:** Enable rewards that span multiple business partners ### Create business engagement for campaign (Admin) - [POST /campaign-engagements/{id}](https://docs.pers.ninja/swagger/campaign-engagements/campaignengagementscontroller_createbusinessengagementforcampaign.md): Add a business engagement relationship to campaign for business-specific rewards. Admin-only operation. Replaces POST /campaign/admin/{id}/business-engagement ### Update business engagement in campaign (Admin) - [PUT /campaign-engagements/{id}/{businessEngagementId}](https://docs.pers.ninja/swagger/campaign-engagements/campaignengagementscontroller_updatebusinessengagementincampaign.md): Update an existing business engagement relationship in campaign. Admin-only operation. Replaces PUT /campaign/admin/{id}/business-engagement/{businessEngagementId} ### Remove business engagement from campaign (Admin) - [DELETE /campaign-engagements/{id}/{businessEngagementId}](https://docs.pers.ninja/swagger/campaign-engagements/campaignengagementscontroller_removebusinessengagementfromcampaign.md): Remove a business engagement relationship from campaign. Admin-only operation. Replaces DELETE /campaign/admin/{id}/business-engagement/{businessEngagementId} ## Campaign Claims ## 🔥 BUSINESS CRITICAL: Financial Claims Processing
BUSINESS CRITICAL: Multi-level reward claim processing with comprehensive fraud prevention and audit trails. Handles actual reward distribution with full financial security and compliance features.
**Critical Security Features:**
• **Multi-Level Access:** USER, BUSINESS, SYSTEM, ADMIN claim processing levels
• **Fraud Prevention:** IP tracking and behavioral analysis for security
• **Audit Compliance:** Complete transaction history for regulatory requirements
• **Financial Attribution:** User and business context preservation for accounting
• **Claim Verification:** Multi-step verification process for high-value rewards
**Access Levels:**
• **USER:** Direct customer reward claims with user authentication
• **BUSINESS:** B2B reward processing with business context attribution
• **SYSTEM:** Automated claims processing via secure API integration
• **ADMIN:** Complete administrative oversight and manual claim processing ### System claim reward (Critical Financial) - [POST /campaign-claims/system](https://docs.pers.ninja/swagger/campaign-claims/campaignclaimscontroller_processsystemclaim.md): Process automated reward claims via system API. BUSINESS CRITICAL - handles real financial transactions. Requires valid tenant system API key. Replaces POST /campaign/system/claim ### Business claim reward (Critical Financial) - [POST /campaign-claims/business](https://docs.pers.ninja/swagger/campaign-claims/campaignclaimscontroller_processbusinessclaim.md): Process reward claims by business accounts for customers. BUSINESS CRITICAL - handles real financial transactions with business attribution and IP tracking. Replaces POST /campaign/business/claim ### User claim reward (Critical Financial) - [POST /campaign-claims](https://docs.pers.ninja/swagger/campaign-claims/campaignclaimscontroller_processuserclaim.md): Process reward claims by authenticated users for their own accounts. BUSINESS CRITICAL - handles real financial transactions with user attribution and IP tracking. Replaces POST /campaign/auth/claim ### Get user claims for campaign - [GET /campaign-claims/me/{campaignId}](https://docs.pers.ninja/swagger/campaign-claims/campaignclaimscontroller_getuserclaimsforcampaign.md): Get authenticated user claim history for specific campaign. Financial records with user attribution. Replaces GET /campaign/auth/{campaignId}/claim ### Get all user claims - [GET /campaign-claims/me](https://docs.pers.ninja/swagger/campaign-claims/campaignclaimscontroller_getalluserclaims.md): Get authenticated user complete claim history across all campaigns. Financial records with user attribution. Replaces GET /campaign/auth/claim ### Get all claims history (Admin) - [GET /campaign-claims/admin](https://docs.pers.ninja/swagger/campaign-claims/campaignclaimscontroller_getallclaimshistory.md): Get complete claims history across all campaigns and users for administrative oversight. Admin-only financial reporting. Replaces GET /campaign/admin/claim ### Get campaign claims history (Admin) - [GET /campaign-claims/admin/{campaignId}](https://docs.pers.ninja/swagger/campaign-claims/campaignclaimscontroller_getcampaignclaimshistory.md): Get all claims for specific campaign for administrative oversight. Admin-only financial reporting. Replaces GET /campaign/admin/{campaignId}/claim ### Get user claims (Admin) - [GET /campaign-claims/admin/users/{userId}](https://docs.pers.ninja/swagger/campaign-claims/campaignclaimscontroller_getclaimsbyuser.md): Get all claims by specific user across all campaigns for administrative oversight. Admin-only financial reporting. Replaces GET /campaign/admin/claim/user/{userId} ### Get business claims (Admin) - [GET /campaign-claims/admin/businesses/{businessId}](https://docs.pers.ninja/swagger/campaign-claims/campaignclaimscontroller_getclaimsbybusiness.md): Get all claims by specific business across all campaigns for administrative oversight. Admin-only financial reporting. Replaces GET /campaign/admin/claim/business/{businessId} ## Redemptions ## Token Exchange System
Token exchange system facilitating conversion between different token types and redemption for rewards. Provides flexible reward experiences through diverse redemption options.
**Redemption Features:**
• **Token Exchange:** Convert between different token types with exchange rates
• **Reward Catalog:** Browse available rewards for token redemption
• **Exchange Rules:** Configure conversion rates and redemption requirements
• **Partner Ecosystem:** Redemption options across business partner networks
• **Flexible Rewards:** Support for products, services, and digital rewards ![Redemption Module](https://s3.eu-west-1.amazonaws.com/pers.assets.prod/tenant/a0df6ebf-51cc-4c18-afcd-0de355c250dc_DemoApp_eXplorins/Documentation/Redemption_image.png) ### Get redemption types - [GET /redemptions/types](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_getredemptiontypes.md): Get all available redemption types for client reference. Requires valid project API key. ### Create redemption type (Admin) - [POST /redemptions/types](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_createredemptiontype.md): Create a new redemption type for system configuration. Replaces POST /redemption/admin/type ### Get redemption by ID - [GET /redemptions/{id}](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_getredemptionbyid.md): Get specific redemption details by ID. Requires valid project API key. ### Update redemption (Admin) - [PUT /redemptions/{id}](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_updateredemption.md): Update existing redemption information. Replaces PUT /redemption/admin/{id} ### Delete redemption (Admin) - [DELETE /redemptions/{id}](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_deleteredemption.md): Permanently delete a redemption. Replaces DELETE /redemption/admin/{id} ### Get redemption available supply - [GET /redemptions/{id}/available-supply](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_getavailablesupply.md): Get the available supply count for a specific redemption. Used for inventory display. ### Redeem redemption (User) - [POST /redemptions/{id}/redeem](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_redeemredemption.md): Execute a redemption for the authenticated user. This is a business-critical operation with IP tracking for fraud prevention. Replaces POST /redemption/auth/redeem ### Get user redemption history - [GET /redemptions/me/history](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_getuserredemptionhistory.md): Get all redemptions executed by the authenticated user. Replaces GET /redemption/auth/redeem ### Get redemptions (Intelligent Access) - [GET /redemptions](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_getredemptions.md): Intelligent endpoint that adapts based on authentication: Public users get active redemptions only, Admin users get all redemptions with optional filtering. Consolidates GET /redemption and GET /redemption/admin ### Create redemption (Admin) - [POST /redemptions](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_createredemption.md): Create a new redemption with administrative privileges. Replaces POST /redemption/admin ### Toggle redemption status (Admin) - [PUT /redemptions/{id}/status](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_toggleredemptionstatus.md): Toggle redemption between active and inactive status. Follows standard /status pattern. Replaces PUT /redemption/admin/{id}/toggle-active ### Add token unit to redemption (Admin) - [POST /redemptions/{id}/token-units](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_addtokenunittoredemption.md): Add a new token unit to an existing redemption. Replaces POST /redemption/admin/{id}/token-units ### Update redemption token unit (Admin) - [PUT /redemptions/{id}/token-units/{tokenUnitId}](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_updatetokenunit.md): Update an existing token unit within a redemption. Replaces PUT /redemption/admin/{id}/token-units/{tokenUnitId} ### Remove token unit from redemption (Admin) - [DELETE /redemptions/{id}/token-units/{tokenUnitId}](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_removetokenunit.md): Remove an existing token unit from a redemption. Replaces DELETE /redemption/admin/{id}/token-units/{tokenUnitId} ## Purchases ## Payment Processing System
Secure payment processing for account balance top-ups through credit card payments. Provides secure financial transactions for premium features and account funding within the loyalty ecosystem.
**Payment Features:**
• **Secure Payments:** Credit card processing with industry-standard security
• **Balance Top-Up:** Add funds to user accounts for premium features
• **Payment Methods:** Support for multiple payment providers and methods
• **Transaction Security:** Encrypted payment data and fraud protection
• **Account Integration:** Seamless integration with token and reward systems ![Purchase Module](https://s3.eu-west-1.amazonaws.com/pers.assets.prod/tenant/a0df6ebf-51cc-4c18-afcd-0de355c250dc_DemoApp_eXplorins/Documentation/Purchase_image.png) ### Stripe payment webhook (Critical) - [POST /purchases/webhooks/stripe](https://docs.pers.ninja/swagger/purchases/purchasescontroller_handlestripewebhook.md): Handles Stripe payment events for financial reconciliation. CRITICAL: Do not modify without extensive testing. Replaces POST /purchase/stripe-webhook ### Get purchase tokens (Intelligent Access) - [GET /purchases/tokens](https://docs.pers.ninja/swagger/purchases/purchasescontroller_getpurchasetokens.md): Intelligent endpoint that adapts based on authentication: Public users get active tokens only, Admin users get filtered tokens. Replaces GET /purchase/token ### Create purchase token (Admin) - [POST /purchases/tokens](https://docs.pers.ninja/swagger/purchases/purchasescontroller_createpurchasetoken.md): Create a new purchase token for the product catalog. Admin-only operation. Replaces POST /purchase/admin/token ### Get donation types - [GET /purchases/donation-types](https://docs.pers.ninja/swagger/purchases/purchasescontroller_getdonationtypes.md): Get all available donation types for public catalog browsing. Requires valid project API key. Replaces GET /purchase/donation/type ### Create donation type (Admin) - [POST /purchases/donation-types](https://docs.pers.ninja/swagger/purchases/purchasescontroller_createdonationtype.md): Create a new donation type for system configuration. Admin-only operation. Replaces POST /purchase/admin/donation/type ### Create payment intent (Financial) - [POST /purchases/payment-intents](https://docs.pers.ninja/swagger/purchases/purchasescontroller_createpaymentintent.md): Create a new Stripe payment intent for purchase processing. Requires tenant context for Stripe API key. FINANCIAL OPERATION - handle with care. Replaces POST /purchase/payment-intent ### Update payment intent (Financial) - [PUT /purchases/payment-intents/{paymentIntentId}](https://docs.pers.ninja/swagger/purchases/purchasescontroller_updatepaymentintent.md): Update an existing Stripe payment intent. Requires tenant context for Stripe API key. FINANCIAL OPERATION - handle with care. Replaces PUT /purchase/payment-intent/{paymentIntentId} ### Cancel payment intent (Financial) - [DELETE /purchases/payment-intents/{paymentIntentId}](https://docs.pers.ninja/swagger/purchases/purchasescontroller_cancelpaymentintent.md): Cancel an existing Stripe payment intent. Requires tenant context for Stripe API key. FINANCIAL OPERATION - handle with care. Replaces DELETE /purchase/payment-intent/{paymentIntentId} ### Create user purchase (Financial Transaction) - [POST /purchases](https://docs.pers.ninja/swagger/purchases/purchasescontroller_createuserpurchase.md): Create a new purchase for the authenticated user. BUSINESS CRITICAL - handles real financial transactions with Stripe integration. Requires user and tenant context. Replaces POST /purchase/auth ### Get user purchase history - [GET /purchases/me/history](https://docs.pers.ninja/swagger/purchases/purchasescontroller_getuserpurchasehistory.md): Get all purchases made by the authenticated user. Financial records require proper user attribution. Replaces GET /purchase/auth ### Update purchase token (Admin) - [PUT /purchases/tokens/{id}](https://docs.pers.ninja/swagger/purchases/purchasescontroller_updatepurchasetoken.md): Update an existing purchase token in the product catalog. Admin-only operation. Replaces PUT /purchase/admin/token/{id} ### Delete purchase token (Admin) - [DELETE /purchases/tokens/{id}](https://docs.pers.ninja/swagger/purchases/purchasescontroller_deletepurchasetoken.md): Delete an existing purchase token from the product catalog. Admin-only operation. Replaces DELETE /purchase/admin/token/{id} ### Create purchase type (Admin) - [POST /purchases/types](https://docs.pers.ninja/swagger/purchases/purchasescontroller_createpurchasetype.md): Create a new purchase type for system configuration. Admin-only operation. Replaces POST /purchase/admin/type ## Businesses ## Partner Ecosystem Management
Business partner management for multi-stakeholder loyalty programs. Handles partner onboarding, collaboration frameworks, and performance tracking within the reward ecosystem.
**Partner Management:**
• **Partner Onboarding:** Register and configure business partners in the ecosystem
• **Collaboration Tools:** Facilitate joint campaigns and cross-partner rewards
• **Performance Analytics:** Track partner engagement and contribution metrics
• **Incentive Structures:** Configure partner-specific reward and commission models
• **Community Building:** Foster collaborative relationships between ecosystem partners ### Create a new business type - [POST /businesses/types](https://docs.pers.ninja/swagger/businesses/businessescontroller_createbusinesstype.md): Create a new business type ### Update a business type - [PUT /businesses/types](https://docs.pers.ninja/swagger/businesses/businessescontroller_updatebusinesstype.md): Update a business type ### Get all business types - [GET /businesses/types](https://docs.pers.ninja/swagger/businesses/businessescontroller_getallbusinesstypes.md): Get all business types ### Delete a business type - [DELETE /businesses/types/{id}](https://docs.pers.ninja/swagger/businesses/businessescontroller_deletebusinesstype.md): Delete a business type ### Get current business info - [GET /businesses/me](https://docs.pers.ninja/swagger/businesses/businessescontroller_getcurrentbusiness.md): Get business info with current token balances (business authentication required) ### Get all businesses - [GET /businesses](https://docs.pers.ninja/swagger/businesses/businessescontroller_getallbusinesses.md): Get all businesses. Project API key users get active businesses only. Admin users (with valid JWT) get full access with query parameters. ### Create a new business - [POST /businesses](https://docs.pers.ninja/swagger/businesses/businessescontroller_createbusiness.md): Create a new business account, will be inactive until activated by admin ### Get business by account address - [GET /businesses/account/{accountAddress}](https://docs.pers.ninja/swagger/businesses/businessescontroller_getbyaccountaddress.md): Get business info by account address ### Get business by ID - [GET /businesses/{id}](https://docs.pers.ninja/swagger/businesses/businessescontroller_getbyid.md): Get business info by ID ### Update a business - [PUT /businesses/{id}](https://docs.pers.ninja/swagger/businesses/businessescontroller_updatebusiness.md): Update a business account ### Create multiple businesses from URL - [POST /businesses/bulk/url](https://docs.pers.ninja/swagger/businesses/businessescontroller_createbusinessesfromurl.md): Create multiple business accounts by fetching a JSON file from the provided URL. The file at the URL is expected to be a JSON object conforming to the BusinessBulkCreateRequestDTO structure, containing an array of business data. ### Toggle business status - [PUT /businesses/{id}/status](https://docs.pers.ninja/swagger/businesses/businessescontroller_togglebusinessstatus.md): Toggle business account active status ### Generate new API key - [PUT /businesses/{id}/api-key](https://docs.pers.ninja/swagger/businesses/businessescontroller_generatenewbusinessapikey.md): Retrieve a new api key and revoke previous ## Transactions ## Transaction Management System
Comprehensive transaction management for credits and tokens with secure processing and real-time balance updates. Handles all financial operations within the loyalty platform.
**Transaction Operations:**
• **Token Minting:** Create new tokens and add to user accounts
• **Token Transfers:** Secure peer-to-peer token transfers between users
• **Token Burning:** Remove tokens from circulation with proper audit trails
• **Balance Queries:** Real-time balance checks across multiple token types
• **Transaction Authorization:** Verify user permissions and sufficient balances
• **Transaction History:** Complete audit logs for all financial operations ### Get authenticated user's sent transactions - [GET /transactions/me/sent](https://docs.pers.ninja/swagger/transactions/transactionscontroller_getusersenttransactions.md): Get transactions where the authenticated user is the sender. Replaces GET /transaction/auth/sender ### Get authenticated user's received transactions - [GET /transactions/me/received](https://docs.pers.ninja/swagger/transactions/transactionscontroller_getuserreceivedtransactions.md): Get transactions where the authenticated user is the recipient. Replaces GET /transaction/auth/recipient ### Get all transactions with pagination (Admin) - [GET /transactions](https://docs.pers.ninja/swagger/transactions/transactionscontroller_getalltransactions.md): Get all transactions with structured pagination and filtering. RLS ensures tenant isolation automatically. Replaces GET /transaction/admin ### Query transactions by sender (Admin) - [POST /transactions/query-sender](https://docs.pers.ninja/swagger/transactions/transactionscontroller_querytransactionsbysender.md): Get transactions by sender for any account. Replaces POST /transaction/admin/sender ### Query transactions by recipient (Admin) - [POST /transactions/query-recipient](https://docs.pers.ninja/swagger/transactions/transactionscontroller_querytransactionsbyrecipient.md): Get transactions by recipient for any account. Replaces POST /transaction/admin/recipient ### Get transaction by ID - [GET /transactions/{id}](https://docs.pers.ninja/swagger/transactions/transactionscontroller_gettransactionbyid.md): Get single transaction by ID. Requires valid project API key. ### Create system transaction (Admin) - [POST /transactions/system](https://docs.pers.ninja/swagger/transactions/transactionscontroller_createsystemtransaction.md): Create any type of transaction (MINT/TRANSFER/BURN) using administrative privileges. Replaces POST /transaction/admin/transaction ### Create user transaction - [POST /transactions/user](https://docs.pers.ninja/swagger/transactions/transactionscontroller_createusertransaction.md): Create transaction for authenticated user. Sender automatically set to authenticated user. Replaces POST /transaction/auth/transaction ### Create business transaction - [POST /transactions/business](https://docs.pers.ninja/swagger/transactions/transactionscontroller_createbusinesstransaction.md): Create transaction for business context. Replaces POST /transaction/business/transaction ### Prepare transaction for client-side signing - [POST /transactions/prepare](https://docs.pers.ninja/swagger/transactions/transactionscontroller_preparetransaction.md): Prepares transaction data for client-side execution. Returns the data needed for the client to sign and submit the transaction. ### Prepare existing transaction for client-side signing - [GET /transactions/{id}/prepare](https://docs.pers.ninja/swagger/transactions/transactionscontroller_preparetransactionbyid.md): Prepares transaction data for client-side execution from existing transaction ID. Returns the data needed for the client to sign and submit the transaction. ### Submit client-side signed transaction - [POST /transactions/{id}/submit](https://docs.pers.ninja/swagger/transactions/transactionscontroller_submittransaction.md): Submits a signed transaction from the client. This method is used to finalize the transaction after the client has signed it. ### Export all transactions as CSV - [GET /transactions/export/csv](https://docs.pers.ninja/swagger/transactions/transactionscontroller_exporttransactionsascsv.md): Downloads all transactions as a CSV file. RLS ensures tenant isolation automatically. File includes all transaction data formatted for business analysis. ### Get transaction analytics - [POST /transactions/analytics](https://docs.pers.ninja/swagger/transactions/transactionscontroller_gettransactionanalytics.md): Get transaction analytics with dynamic filtering, grouping, and metrics. Optimized for dashboard modules: stamps count, rewards analysis, top users, etc. RLS ensures tenant isolation automatically. ## Users ## User Account Management
User account management and profile operations for loyalty platform participants. Handles user registration, authentication, profile management, and account lifecycle.
**User Operations:**
• **Account Registration:** User signup and profile creation with verification
• **Authentication:** Secure login and session management
• **Profile Management:** User profile updates and preference configuration
• **Account Security:** Password management and two-factor authentication
• **Privacy Controls:** Data management and privacy settings for users ### Get current user info - [GET /users/me](https://docs.pers.ninja/swagger/users/userscontroller_getcurrentuser.md): Get authenticated user account info without balances ### Update current user - [PUT /users/me](https://docs.pers.ninja/swagger/users/userscontroller_updatecurrentuser.md): Update authenticated user account ### Get current user balance - [GET /users/me/balance](https://docs.pers.ninja/swagger/users/userscontroller_getcurrentuserbalance.md): Get authenticated user account with current token balances ### Get current user status - [GET /users/me/status](https://docs.pers.ninja/swagger/users/userscontroller_getcurrentuserstatus.md): Get authenticated user status types ### Check if user exists - [GET /users/exists](https://docs.pers.ninja/swagger/users/userscontroller_checkuserexists.md): Check if a user exists using any identifier field (id, email, etc.) ### Get all public profiles - [GET /users/public](https://docs.pers.ninja/swagger/users/userscontroller_getallpublicprofiles.md): Get all public user profiles ### Get public profile - [GET /users/public/{id}](https://docs.pers.ninja/swagger/users/userscontroller_getpublicprofile.md): Get a public profile by user ID ### Get all user status types - [GET /users/status-types](https://docs.pers.ninja/swagger/users/userscontroller_getalluserstatustypes.md): Get all available user status types ### Create user status type - [POST /users/status-types](https://docs.pers.ninja/swagger/users/userscontroller_createuserstatustype.md): Create user status type as admin ### Get user status type - [GET /users/status-types/{id}](https://docs.pers.ninja/swagger/users/userscontroller_getuserstatustype.md): Get a user status type by ID ### Update eligible token for status type - [PUT /users/status-types/{id}/eligible-tokens/{tokenAddress}](https://docs.pers.ninja/swagger/users/userscontroller_updateuserstatustypeeligibletoken.md): Add or remove eligible token for user status type as admin ### Get user info - [POST /users/info](https://docs.pers.ninja/swagger/users/userscontroller_getuserinfo.md): Get user account info without balances (business with user management permission OR admin authentication required) ### Get user balance - [POST /users/balance](https://docs.pers.ninja/swagger/users/userscontroller_getuserbalance.md): Get user account with current token balances (business with user management permission OR admin authentication required) ### Create or update user account - [POST /users](https://docs.pers.ninja/swagger/users/userscontroller_createorupdateuser.md): Create or update user account(s). Supports single user (business/admin) or bulk operations (admin only) ### Get all users - [GET /users](https://docs.pers.ninja/swagger/users/userscontroller_getallusers.md): Get all users with role-based access. Project API key users get public profiles only. Admin users get full access with query parameters. ### Get user by ID - [GET /users/{id}](https://docs.pers.ninja/swagger/users/userscontroller_getuserbyid.md): Get user by any identifier field (admin only) ### Update user (admin) - [PUT /users/{id}](https://docs.pers.ninja/swagger/users/userscontroller_updateuseradmin.md): Update user account as admin ### Create users from URL (admin) - [POST /users/bulk/url](https://docs.pers.ninja/swagger/users/userscontroller_createusersfromurl.md): Create user accounts from external URL as admin ### Toggle user status - [PUT /users/{id}/status](https://docs.pers.ninja/swagger/users/userscontroller_toggleuserstatus.md): Toggle user active status as admin ## Balances ## Account Balance Management
Real-time balance tracking and management across all token types and user accounts. Provides comprehensive balance queries and balance-related operations.
**Balance Features:**
• **Multi-Token Balances:** Track balances across different token types per user
• **Real-Time Updates:** Instant balance updates from all transaction sources
• **Balance History:** Historical balance tracking and change audit trails
• **Balance Queries:** Flexible balance lookup with filtering and aggregation
• **Balance Notifications:** Alert systems for balance changes and thresholds ### Get account balance by address (Admin) - [GET /balances/accounts/{accountAddress}](https://docs.pers.ninja/swagger/balances/balancescontroller_getaccountbalance.md): Get detailed balance information including token metadata for any account address. Requires tenant admin privileges. Replaces GET /balance/admin/account/{accountAddress} ## Files ## File Management System
File upload and management system for platform assets including campaign images, user avatars, and document attachments with secure storage and access control.
**File Operations:**
• **Secure Upload:** File upload with type validation and security scanning
• **Asset Management:** Organize and manage platform media assets
• **Access Control:** Role-based file access and sharing permissions
• **CDN Integration:** Fast global file delivery through content delivery networks
• **File Processing:** Automatic image resizing and format optimization ### Generate signed URL for entity storage - [POST /files/entity-storage-url](https://docs.pers.ninja/swagger/files/filescontroller_getentitystorageurl.md): Creates S3 signed URLs for uploading or downloading entity files. Supports both business and admin authentication flows. ## Web3 Chains ## Blockchain Network Management
Blockchain network configuration and management for multi-chain token operations. Handles network connections, chain switching, and blockchain-specific operations.
**Chain Operations:**
• **Multi-Chain Support:** Connect to multiple blockchain networks simultaneously
• **Network Configuration:** Configure blockchain endpoints and network parameters
• **Chain Switching:** Dynamic switching between different blockchain networks
• **Network Status:** Real-time monitoring of blockchain network health and status
• **Gas Management:** Optimize transaction costs across different networks ### Get Web3 chain data by chain ID - [GET /chains/{chainId}](https://docs.pers.ninja/swagger/web3-chains/web3chainscontroller_getchaindata.md): Retrieve comprehensive chain data including authentication JWT token valid for 30 days. Supports both mainnet and testnet chains. ## Contracts ## Smart Contract Management
Smart contract deployment and interaction management for blockchain-based loyalty operations. Handles contract lifecycle and blockchain integration.
**Contract Operations:**
• **Contract Deployment:** Deploy loyalty-related smart contracts to blockchain networks
• **Contract Interaction:** Execute smart contract functions for token operations
• **Contract Monitoring:** Track contract events and transaction confirmations
• **Contract Upgrades:** Manage contract versioning and upgrade procedures
• **Multi-Chain Contracts:** Deploy and manage contracts across multiple blockchains ### Create a new Web3 contract (Admin) - [POST /contracts](https://docs.pers.ninja/swagger/contracts/web3contractscontroller_createcontract.md): Create a new Web3 contract with administrative privileges. Requires tenant admin access. Replaces POST /contract ## Auth ## Authentication & Authorization
Comprehensive authentication and authorization system supporting multiple access levels including users, businesses, admins, and system-level access with JWT-based security.
**Auth Features:**
• **Multi-Level Access:** Support for USER, BUSINESS, ADMIN, SYSTEM authentication levels
• **JWT Security:** JSON Web Token-based authentication with secure key management
• **Role-Based Access:** Fine-grained permission system with role hierarchy
• **API Key Management:** Secure API key generation and validation for system integrations
• **Session Management:** Secure session handling with automatic expiration and refresh ### Create authentication token - [POST /auth/token](https://docs.pers.ninja/swagger/auth/authcontroller_createtoken.md): Universal token creation supporting multiple authentication flows: USER TOKEN CREATION (External Providers): - Header: X-API-Key (tenant identification) - Body: { authToken: "jwt_from_provider" } - Supported providers: DFNS, Firebase, Auth0, Okta ADMIN TOKEN CREATION: - Header: Authorization: Bearer admin_jwt - Body: {} (admin context from JWT) - Returns tenant-scoped admin tokens FUTURE EXTENSIBILITY: - Provider-specific token exchange flows - Multi-provider token creation patterns - Automatic provider detection and validation ### Refresh authentication tokens - [POST /auth/refresh](https://docs.pers.ninja/swagger/auth/authcontroller_refresh.md): Refresh access tokens using valid refresh token ## Root ## Platform Infrastructure
Core platform infrastructure endpoints including health checks, system status, and platform configuration. Provides essential system-level operations and monitoring.
**Infrastructure Operations:**
• **Health Monitoring:** System health checks and status reporting
• **Platform Status:** Real-time platform operational status
• **Configuration Access:** System configuration and environment information
• **Diagnostic Tools:** Platform diagnostics and troubleshooting endpoints
• **System Integration:** Core infrastructure for system-level operations ### RootController_get - [GET /](https://docs.pers.ninja/swagger/root/rootcontroller_get.md) ### RootController_getCurrentTime - [GET /healthcheck](https://docs.pers.ninja/swagger/root/rootcontroller_getcurrenttime.md) ### Check if tenant system api key is valid - [GET /system](https://docs.pers.ninja/swagger/root/rootcontroller_getsystem.md): Check if tenant system api key is valid ### ADMIN: Check if admin - [GET /admin](https://docs.pers.ninja/swagger/root/rootcontroller_getadmin.md): Get if admin ### RootController_testGeo - [GET /geolocation](https://docs.pers.ninja/swagger/root/rootcontroller_testgeo.md) ## Well-known ## Security Infrastructure
JSON Web Key Set (JWKS) endpoints for JWT token verification. Provides public keys for secure authentication token validation across the platform ecosystem.
**Security Features:**
• **JWKS Endpoints:** Standard JSON Web Key Set for JWT verification
• **Public Key Distribution:** Secure distribution of verification keys
• **Token Validation:** Enable third-party JWT token verification
• **Security Standards:** Compliance with OAuth 2.0 and OpenID Connect
• **Cross-Platform Auth:** Support for distributed authentication verification ### Get JWKS - [GET /.well-known/jwks.json](https://docs.pers.ninja/swagger/well-known/jwkscontroller_getjwks.md)