PERS API Changelog

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

Current Version: 2.0.17

• Enhanced Platform Detection: Added automatic User-Agent parsing as fallback when SDK doesn't provide platform information (OS, browser, device type)
• Data Quality Tracking: Platform data now includes quality indicator (platformSource: 'sdk' | 'auto') to distinguish authoritative vs auto-detected information
• Mobile Browser Tracking: Mobile browsers (Chrome, Safari on phones/tablets) now correctly tracked as channel: 'web' - check platform.deviceType to distinguish mobile vs desktop web users

• Added database-level unique email constraint per tenant to prevent duplicate registrations and race conditions

• Attribution Tracking: New attribution tracking for analytics across all entities (users, claims, redemptions, bookings)
• DataSource Headers: SDK can send x-source-channel, x-source, x-source-medium, x-source-campaign headers for campaign tracking

• Auto-detects channel/source from User-Agent and Referer headers when SDK headers not provided
• Standalone serverless function for booking operations
• Users now have registrationSource field for analytics

• Business Ownership: Added ownerBusinessId field to campaigns, redemptions, and token metadata for tracking which business owns/promotes the entity
• Owner Business Loading: Added ?include=ownerBusiness query parameter to load owner business entity details
• Owner Business Filtering: Added ?ownerBusinessId filter parameter to campaigns, redemptions, and token metadata endpoints

• Deprecated CampaignBusinessEngagement: Use TriggerSource.businessId for business participation tracking instead
• Business Loading: ?include=businesses now extracts business IDs from TriggerSources instead of deprecated CampaignBusinessEngagement

• Booking Terminology: Renamed "reservation" to "booking" throughout the API for clarity
• Simplified Booking Types: Booking requirement values now: 'active', 'future', 'past', 'active_future', 'any', or null (removed 'none')
• Enhanced Redemption Includes: Redemptions now support ?include=userInfo,booking to load user field validation and booking eligibility data
• Booking Query Filters: GET /bookings endpoint now supports ?userId and ?businessId query parameters

• Terminology Change: All "reservation" references changed to "booking" (reservationRequirement → bookingRequirement)
• Removed Endpoint: GET /users/:id/bookings removed - use GET /bookings?userId=:id instead
• Type Change: BookingRequirementType value 'none' removed - use null instead

• Transaction Metadata URIs: Added metadataUri field to transactions for tracking IPFS/storage URLs of NFT metadata
• Structured Auth Errors: Token refresh failures now return specific error codes (REFRESH_TOKEN_EXPIRED, REFRESH_TOKEN_REVOKED) for programmatic detection
• Redemption Type Management: Added PUT /redemptions/types/:id and DELETE /redemptions/types/:id endpoints for admin management

• DPoP Clock Tolerance: Increased tolerance for corporate environments with clock drift (10 min past, 5 min future)

• Date Range Filtering: Added dateFrom and dateTo query parameters to campaign claims and redemption redeems endpoints
• Multi-Tag Filtering: Added tags parameter (OR match) on campaigns, redemptions, and businesses for flexible tag-based queries
• Business Search: Added search parameter to GET /businesses endpoint for name-based searching
• Immediate Activation: Added isActive option to activate redemptions and token metadata immediately upon creation

• User Endpoints: Fixed PUT /users/me, POST /users/info, and PUT /users/:identifier to return virtual wallets in response
• Date Validation: Invalid date formats now return proper 400 Bad Request errors instead of silently failing

• Custom Field Definitions: Added support for custom user information fields with validation rules
• User Info Validation: New POST /users/info endpoint for submitting and validating custom field data
• Geocoding v2: Enhanced geocoding with support for address components, place IDs, and improved accuracy
• Analytics Enhancements: Added totalClaims, totalRedemptions, totalBurns metrics to user analytics
• Owner Business Filtering: Analytics endpoints now support ownerBusinessId filter for business-specific reporting

• Auto-Enrichment: Analytics results now automatically include campaign/redemption names and owner business IDs
• Transaction Status Filtering: Analytics now filters to SUCCEEDED and BROADCASTED transactions by default
• SQL Query Performance: Fixed PostgreSQL column quoting and JOIN syntax for analytics queries

• OIDC Discovery: Added /.well-known/openid-configuration endpoint for enterprise SSO integration
• Webhook Metadata: Webhook trigger endpoint now returns structured response with executionId, statusCode, durationMs

• Improved platform stability for high-traffic multi-tenant scenarios