PERS API Changelog

Public changelog for the PERS Platform API. Tracking started April 2026.

Current Version: 2.0.56

• Added ownerBusinessId field to campaigns, redemptions, and token metadata for business ownership tracking
• Added ?include=ownerBusiness query parameter to load owner business entity on campaigns, redemptions, and token metadata
• Added ?ownerBusinessId filter parameter to campaigns, redemptions, and token metadata endpoints

• Deprecated CampaignBusinessEngagement - use TriggerSource.businessId for business participation instead
• Updated ?include=businesses to extract business IDs from TriggerSources instead of deprecated CampaignBusinessEngagement

• New attribution tracking for analytics across all entities (users, claims, redemptions, bookings)

• Auto-detects channel/source from User-Agent and Referer headers
• SDK can send x-source-* headers for campaign/medium tracking
• Standalone serverless function for booking operations
• Users now have registrationSource field for analytics

• Renamed "reservation" terminology to "booking" for redemption eligibility requirements
• Simplified booking requirement types: 'active', 'future', 'past', 'active_future', 'any' (no 'none')
• Redemptions now return userInfo and booking data via ?include=userInfo,booking
• GET /bookings endpoint now supports userId and businessId query filters
• Analytics endpoints now support ownerBusinessId filter for business-specific reporting
• User analytics endpoint now returns totalClaims, totalRedemptions, totalBurns metrics
• Analytics results now include campaign/redemption names and owner business ID automatically

• Added metadataUri field to transactions for tracking IPFS/storage URLs of NFT metadata
• Added structured error codes for token refresh failures (REFRESH_TOKEN_EXPIRED, REFRESH_TOKEN_REVOKED)
• Added PUT and DELETE endpoints for redemption types

• Improved DPoP clock tolerance for corporate environments (10 min past, 5 min future)

• Added dateFrom and dateTo query filters to campaign claims and redemption redeems endpoints
• Added multi-tag filtering (OR match) with tags parameter on campaigns, redemptions, and businesses
• Added search parameter to GET /businesses endpoint
• Added isActive option for immediate activation when creating redemptions and token metadata

• Fixed PUT /users/me, POST /users/info, and PUT /users/:identifier to return virtual wallets
• Fixed date parameter validation - invalid date formats now return 400 Bad Request

• Added startDate, endDate, and terms fields to Redemption entity
• Added registrationNumber field to Business entity for company registration/VAT numbers
• Added startDate and endDate query filters to GET /campaigns and GET /redemptions
• Added claimCount include option for campaigns (?include=claimCount)
• Added redeemCount include option for redemptions (?include=redeemCount)

• Improved error responses to preserve original error domain instead of inferring from URL path

• Added template interpolation for ERC721 token name/description using {{placeholder}} syntax
• Added {{user.firstName}}, {{campaign.name}}, {{business.displayName}}, {{context.xxx}}, {{defaults.xxx}} placeholder support
• Added context field to POST /transactions for direct ERC721 mints with template interpolation

• Template interpolation is free (no AI cost) and instant
• Improved API documentation for dynamic context and template interpolation in Swagger

• Fixed AI prompts now support {{context.xxx}} placeholder interpolation
• Fixed allowExternalContextOverwrite not persisting on token metadata update

• Added dynamic context support for ERC721 token generation with AI prompts
• Added trigger-based validity for NFT expiry (validityDate, validityEndDate, validityDuration)
• Added context field to TriggerSource for admin-defined dynamic data
• Added context field to CampaignClaimRequest for user-provided context
• Added context field to Redemption for admin-defined dynamic data
• Added context field to RedemptionRedeemRequest for user-provided context
• Added defaultPromptContext to TokenMetadata for AI prompt defaults

• Added allowExternalContextOverwrite to TokenMetadata for security control

• Added logoUrl field to Campaign, Business, Redemption DTOs for branding customization
• Added projectLogoUrl field to Tenant DTOs for project branding
• Added terms field to CampaignTrigger for Terms & Conditions support

• Enhanced API documentation for campaign claims with detailed integration guides
• GET /tenants/me now returns full tenant data for authenticated tenant admins
• GET /businesses/account/:address now uses wallet-based lookup for multi-chain support

• Improved security for Stripe credential storage with encryption at rest

• Added OIDC discovery endpoint at /.well-known/openid-configuration for enterprise SSO integration

• Improved platform stability for high-traffic multi-tenant scenarios
• Webhook trigger endpoint now returns structured response with execution metadata (executionId, statusCode, durationMs)