Rules

The Rules API allows you to create and manage rules for campaigns in advanced mode. Rules define the triggers, conditions, and effects that power your loyalty campaigns.

Overview

• Base URL: https://api.monterosa.cloud/loyalty/v1

• Authentication: Bearer token required

• Org Context: X-Monterosa-Org-ID header required

Endpoints

List Rules

Get all rules for a specific campaign.

GET /v1/campaigns/{campaignId}/rules

Path Parameters:

• campaignId (string, required) - Campaign ID

Response:

{
  "success": true,
  "data": {
    "rules": [
      {
        "ruleId": "rule_123e4567-e89b-12d3-a456-426614174000",
        "campaignId": "camp_123e4567-e89b-12d3-a456-426614174000",
        "triggerType": "poll_vote",
        "conditions": [
          {
            "field": "vote.option",
            "operator": "equals",
            "value": "TeamA"
          }
        ],
        "effects": [
          {
            "type": "award_points",
            "params": {
              "amount": 10
            }
          }
        ],
        "priority": 5,
        "enabled": true,
        "createdAt": "2025-10-05T12:00:00.000Z",
        "updatedAt": "2025-10-05T12:00:00.000Z"
      }
    ]
  }
}

Create Rule

Create a new rule for a campaign (advanced mode only).

POST /v1/campaigns/{campaignId}/rules

Path Parameters:

• campaignId (string, required) - Campaign ID

Request Body:

{
  "triggerType": "poll_vote",
  "conditions": [
    {
      "field": "vote.option",
      "operator": "equals",
      "value": "TeamA"
    }
  ],
  "effects": [
    {
      "type": "award_points",
      "params": {
        "amount": 10
      }
    }
  ],
  "priority": 5,
  "enabled": true
}

Required Fields:

• triggerType (string) - Type of trigger event

• effects (array) - At least one effect is required

Optional Fields:

• conditions (array) - Conditions that must be met

• priority (number) - Rule priority (default: 5)

• enabled (boolean) - Whether rule is active (default: true)

Response: 201 Created

{
  "success": true,
  "data": {
    "ruleId": "rule_123e4567-e89b-12d3-a456-426614174000",
    "campaignId": "camp_123e4567-e89b-12d3-a456-426614174000",
    "orgId": "00000000-0000-0000-0000-000000000001",
    "triggerType": "poll_vote",
    "conditions": [...],
    "effects": [...],
    "priority": 5,
    "enabled": true,
    "generatedBy": "api_advanced_mode",
    "executionCount": 0,
    "lastExecutedAt": null,
    "createdAt": "2025-10-05T12:00:00.000Z",
    "updatedAt": "2025-10-05T12:00:00.000Z"
  }
}

Error Cases:

• 400 - Campaign is in simple mode (cannot manually create rules)

• 400 - Missing required fields

• 404 - Campaign not found

Update Rule

Update an existing rule.

PATCH /v1/campaigns/{campaignId}/rules/{ruleId}

Path Parameters:

• campaignId (string, required) - Campaign ID

• ruleId (string, required) - Rule ID

Request Body:

{
  "priority": 10,
  "enabled": false
}

Updatable Fields:

• triggerType

• conditions

• effects

• priority

• enabled

Response: 200 OK

{
  "success": true,
  "data": {
    "ruleId": "rule_123e4567-e89b-12d3-a456-426614174000",
    "priority": 10,
    "enabled": false,
    "updatedAt": "2025-10-05T13:00:00.000Z",
    ...
  }
}

Error Cases:

• 400 - Empty request body

• 400 - Rule belongs to different campaign

• 404 - Rule not found

Delete Rule

Permanently delete a rule.

DELETE /v1/campaigns/{campaignId}/rules/{ruleId}

Path Parameters:

• campaignId (string, required) - Campaign ID

• ruleId (string, required) - Rule ID

Response: 204 No Content

Error Cases:

• 400 - Rule belongs to different campaign

• 404 - Rule not found

Trigger Types

Supported trigger types:

• poll_vote - User votes in a poll

• quiz_answer - User answers a quiz question

• prediction_made - User makes a prediction

• message_sent - User sends a message

• page_view - User views a page

• custom_event - Custom event type

Effect Types

Supported effect types:

• award_points - Award points to user

• award_badge - Award a badge

• update_tier - Update user tier

• send_notification - Send notification

• trigger_webhook - Call external webhook

Conditions

Conditions support various operators:

• equals - Exact match

• not_equals - Not equal

• greater_than - Numeric comparison

• less_than - Numeric comparison

• contains - String/array contains

• in - Value in array

• regex - Regular expression match

Testing Results

All Rules API endpoints tested and validated:

• ✅ 26/26 tests passing

• ✅ Average response time < 2s

• ✅ Full CRUD operations

• ✅ Validation and error handling

• ✅ Multi-tenant isolation

Notes

• Rules can only be manually created for campaigns in advanced mode

• Simple mode campaigns have auto-generated rules from trigger/effect definitions

• Rules are executed in priority order (higher priority first)

• Disabled rules are not executed

• All timestamps in ISO 8601 format (UTC)