Loyalty API (Beta)

The Monterosa Loyalty API provides a comprehensive campaign management and loyalty rewards system for engaging your audience.

Notice: This API is currently in beta. Features and endpoints may change before general availability.

Overview

The Loyalty API is a campaign-centric system designed to create, manage, and track loyalty programs, rewards, challenges, and competitions. It supports both simplified mode (for UI-driven campaign creation) and advanced mode (for programmatic rule management).

The Loyalty API uses the Monterosa Fan Firehose to convert engagement into rewards, plus it supports other sources of data, events and triggers from third party systems.

Key Features

• Campaign Management: Create and manage Challenge, Reward, Badge, Streak, and Competition campaigns

• Dual-Mode System: Simple mode for UI-driven workflows, advanced mode for complex rule-based campaigns

• Real-time Event Processing: Process user actions and trigger rewards instantly

• Flexible Segmentation: Target specific user groups with custom segments

• Trigger & Effect System: Powerful rule engine for automating loyalty rewards

• Transaction Tracking: Complete audit trail of all points, XP, and currency changes

• Webhook Integration: Real-time notifications for loyalty events

• Multi-tenant Architecture: Isolated data per organization

Base URL

https://api.monterosa.cloud/loyalty/v1

All API endpoints are versioned with /v1 prefix for forward compatibility.

Authentication

All API requests require Bearer token authentication:

Authorization: Bearer YOUR_API_TOKEN

Additionally, all requests must include an organization ID header:

X-Monterosa-Org-ID: your-org-id

Response Format

All successful responses follow this structure:

{
  "success": true,
  "data": {
    // Response data
  },
  "timestamp": "2025-10-05T12:00:00.000Z"
}

Error responses:

{
  "success": false,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE"
  },
  "timestamp": "2025-10-05T12:00:00.000Z"
}

API Sections

Core APIs (Deployed ✅)

Campaign Management

• Campaigns API - Create and manage loyalty campaigns with advanced features (13 endpoints)

• Rules API - Define rules for advanced mode campaigns (4 endpoints)

• Segments API - Target specific user groups with dynamic and static segments (6 endpoints)

Products & Rewards

• Products API - Manage products, badges, and stock levels (6 endpoints)

• Rewards API - Configure and grant rewards to users (6 endpoints)

• Code Pools - Manage unique code pools for product redemption (4 endpoints)

User Management

• User Profiles API - Manage user data, schemas, and GDPR compliance (8 endpoints)

• Enrollment API - Enroll users in campaigns and loyalty programs (1 endpoint)

• Bulk Operations API - Bulk import and update user data (2 endpoints)

• User Schema API - Discover available user properties for segmentation (1 endpoint)

Engagement & Tracking

• Transactions API - Record and query loyalty transactions (2 endpoints)

• Activity API - Track recent platform activity and events (1 endpoint)

• Social Tracking API - Reward social media actions (4 endpoints)

Configuration & Insights

• Settings API - Manage loyalty program settings (2 endpoints)

• Custom Fields API - Define custom user attributes (5 endpoints)

• Analytics API - Campaign performance metrics and insights (1 endpoint)

• Status API - System health and status reporting (1 endpoint)

Integration & Webhooks

• Webhooks - Configure real-time event notifications (7 endpoints)

• Public Feeds - Public RSS feeds for campaigns and products (2 endpoints)

• Third-Party Integration - Integration guides for external systems

Reference Data

• Triggers API - Available trigger types (1 endpoint)

• Effects API - Available effect types (1 endpoint)

Quick Start

1. Create a Simple Mode Campaign

curl -X POST https://api.monterosa.cloud/loyalty/v1/campaigns \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Engagement Reward",
    "description": "Earn points for daily interactions",
    "type": "Reward",
    "mode": "always-on",
    "triggers": [{
      "eventType": "poll_vote",
      "conditions": { "action": "vote" }
    }],
    "effects": [{
      "type": "award_points",
      "params": { "amount": 10 }
    }]
  }'

2. Create an Advanced Mode Campaign with Rules

# Create campaign (no triggers = advanced mode)
curl -X POST https://api.monterosa.cloud/loyalty/v1/campaigns \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Complex Loyalty Program",
    "type": "Challenge",
    "mode": "always-on"
  }'

# Add rules to campaign
curl -X POST https://api.monterosa.cloud/loyalty/v1/campaigns/CAMPAIGN_ID/rules \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "triggerType": "poll_vote",
    "conditions": [
      {
        "field": "vote.option",
        "operator": "equals",
        "value": "TeamA"
      }
    ],
    "effects": [
      {
        "type": "award_points",
        "params": { "amount": 10 }
      }
    ],
    "priority": 5,
    "enabled": true
  }'

Campaign Types

Challenge

Time-bound or goal-based challenges that users can complete for rewards.

Reward

Action-based rewards that trigger automatically when users perform specific actions.

Badge

Achievement badges that users can collect based on accomplishments.

Streak

Consecutive action tracking with escalating rewards for maintaining streaks.

Competition

Competitive leaderboards where users compete for top positions and rewards.

Campaign Modes

Simple Mode (Simplified)

• UI-driven campaign creation

• Single trigger + effects configuration

• Rules generated automatically

• Best for straightforward reward scenarios

Advanced Mode

• Programmatic rule creation via API

• Multiple rules per campaign

• Complex condition logic (AND/OR)

• Priority-based rule execution

• Best for complex loyalty logic

Time-Based Modes

• always-on: Campaign runs indefinitely

• time-bound: Campaign runs between start and end dates

• recurring: Campaign repeats on a schedule

Rate Limits

• Standard tier: 1000 requests per hour per organization

• Premium tier: 10000 requests per hour per organization

Rate limit headers are included in all responses:

• X-RateLimit-Limit: Maximum requests per hour

• X-RateLimit-Remaining: Remaining requests

• X-RateLimit-Reset: Timestamp when limit resets

Webhooks

Configure webhooks to receive real-time notifications for loyalty events:

• campaign.created

• campaign.updated

• campaign.archived

• transaction.created

• user.tier_changed

• user.badge_earned

Webhook payloads are signed with HMAC SHA256 for verification.

Support

For API support, contact: [email protected]