Enrollment

Enroll new users in the loyalty program with automatic welcome bonuses and event tracking

The Enrollment API provides a streamlined endpoint for onboarding new users into your loyalty program. It combines user creation, welcome bonus distribution, and enrollment event tracking into a single atomic operation.

Overview

Benefits of Using Enrollment Endpoint:

One-stop onboarding: Creates user + transaction + event in single request
Automatic welcome bonuses: Configurable points, XP, and coins
Event triggering: Automatically fires user_enrolled event for campaigns
Referral tracking: Built-in referral attribution
Next steps guidance: Returns actionable next steps for UI

Endpoint

Enroll User

POST /v1/users/enroll

Enroll a new user with welcome bonuses and trigger onboarding campaigns.

Request Body:

{
  "userId": "user_12345",
  "email": "[email protected]",
  "name": "John Smith",
  "source": "web_signup",
  "channel": "organic",
  "referredBy": "user_67890",
  "welcomeBonus": {
    "points": 150,
    "coins": 75,
    "xp": 50
  },
  "customFields": {
    "marketingConsent": true,
    "language": "en",
    "country": "GB"
  }
}

Required Fields:

Field

Type

Description

userId

string

Unique user identifier

email

string

Valid email address

Optional Fields:

Field

Type

Default

Description

name

string

Email prefix

User's display name

source

string

"api"

Enrollment source (web, mobile, kiosk, etc)

channel

string

"direct"

Marketing channel (organic, paid, referral, etc)

referredBy

string

User ID of referrer

welcomeBonus

object

See below

Custom welcome rewards

customFields

object

{}

Additional custom data

Default Welcome Bonuses:

{
  "welcomeBonus": {
    "points": 100,
    "coins": 50,
    "xp": 0
  }
}

Example Requests

Basic Enrollment

curl -X POST https://api.monterosa.cloud/loyalty/v1/users/enroll \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_12345",
    "email": "[email protected]",
    "name": "John Smith"
  }'

Enrollment with Referral

curl -X POST https://api.monterosa.cloud/loyalty/v1/users/enroll \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_12345",
    "email": "[email protected]",
    "name": "John Smith",
    "source": "referral_link",
    "referredBy": "user_67890"
  }'

Custom Welcome Bonus

curl -X POST https://api.monterosa.cloud/loyalty/v1/users/enroll \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_12345",
    "email": "[email protected]",
    "welcomeBonus": {
      "points": 500,
      "coins": 200,
      "xp": 100
    }
  }'

Response

Success Response (201 Created)

{
  "success": true,
  "data": {
    "user": {
      "orgId": "org_123",
      "userId": "user_12345",
      "name": "John Smith",
      "email": "[email protected]",
      "tier": "bronze",
      "points": 100,
      "xp": 0,
      "coins": 50,
      "badges": [],
      "customFields": {
        "enrollmentDate": "2025-10-07T10:00:00Z",
        "enrollmentSource": "web_signup",
        "onboardingStage": "welcome",
        "referredBy": "user_67890"
      },
      "createdAt": "2025-10-07T10:00:00Z",
      "updatedAt": "2025-10-07T10:00:00Z",
      "createdBy": "api-admin"
    },
    "welcome": {
      "pointsAwarded": 100,
      "coinsAwarded": 50,
      "xpAwarded": 0,
      "transactionId": "txn_welcome_abc123",
      "eventId": "event_enroll_def456"
    },
    "nextSteps": [
      {
        "action": "profile_completion",
        "description": "Complete your profile to earn 100 bonus points",
        "endpoint": "PATCH /v1/users/user_12345"
      },
      {
        "action": "view_campaigns",
        "description": "Check out available campaigns and rewards",
        "endpoint": "GET /v1/campaigns?status=active"
      },
      {
        "action": "check_progress",
        "description": "Track your onboarding progress",
        "endpoint": "GET /v1/users/user_12345/challenges"
      }
    ]
  }
}

Error Responses

400 Bad Request - Validation failure:

{
  "success": false,
  "error": {
    "message": "Validation failed",
    "errors": [
      "email is required and must be a string",
      "email must be a valid email address"
    ]
  }
}

409 Conflict - User already enrolled:

{
  "success": false,
  "error": {
    "message": "User already enrolled"
  }
}

What Happens During Enrollment

The enrollment endpoint performs these operations atomically:

Create User Profile
- Sets initial tier to bronze
- Awards welcome bonuses
- Stores enrollment metadata
Create Welcome Transaction
- Records welcome points in transactions table
- Marks as completed status
- Tags with enrollmentBonus: true
Trigger Enrollment Event
- Creates user_enrolled event
- Processed by campaign rules engine
- Can trigger welcome campaigns/badges
Return Next Steps
- Provides actionable endpoints for UI
- Guides user through onboarding
- Links to relevant campaigns

Integration Patterns

Frontend Integration

async function enrollUser(userData) {
  try {
    const response = await fetch('/v1/users/enroll', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiToken}`,
        'X-Monterosa-Org-ID': orgId,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        userId: userData.id,
        email: userData.email,
        name: userData.name,
        source: 'web_signup'
      })
    });

    const result = await response.json();

    if (result.success) {
      // Show welcome message
      showWelcome(result.data.welcome);

      // Navigate to onboarding
      navigateTo('/onboarding', {
        nextSteps: result.data.nextSteps
      });
    }
  } catch (error) {
    console.error('Enrollment failed:', error);
  }
}

Backend Integration

import requests

def enroll_user(user_data, api_token, org_id):
    response = requests.post(
        'https://api.monterosa.cloud/loyalty/v1/users/enroll',
        headers={
            'Authorization': f'Bearer {api_token}',
            'X-Monterosa-Org-ID': org_id,
            'Content-Type': 'application/json'
        },
        json={
            'userId': user_data['id'],
            'email': user_data['email'],
            'name': user_data['name'],
            'source': 'backend_signup',
            'customFields': {
                'signupMethod': 'oauth',
                'provider': user_data.get('provider', 'email')
            }
        }
    )

    if response.status_code == 201:
        data = response.json()['data']
        print(f"Enrolled user {data['user']['userId']}")
        print(f"Welcome bonus: {data['welcome']['pointsAwarded']} points")
        return data
    else:
        print(f"Enrollment failed: {response.json()}")
        return None

Onboarding Flow Example

Complete enrollment-to-onboarding flow:

// Step 1: Enroll user
const enrollment = await enrollUser({
  userId: 'user_123',
  email: '[email protected]',
  source: 'web'
});

// Step 2: Show welcome screen
showWelcomeScreen({
  points: enrollment.welcome.pointsAwarded,
  coins: enrollment.welcome.coinsAwarded
});

// Step 3: Fetch welcome campaigns
const campaigns = await fetch('/v1/campaigns?status=active&tags=welcome');

// Step 4: Track first action
await fetch('/v1/social/events', {
  method: 'POST',
  body: JSON.stringify({
    userId: 'user_123',
    eventType: 'profile_completed',
    eventData: { fields: ['avatar', 'bio'] }
  })
});

// Step 5: Check for rewards
const notifications = await fetch('/v1/users/user_123/notifications');
showRewards(notifications);

Campaign Integration

Create campaigns that trigger on enrollment:

{
  "name": "Welcome Campaign",
  "type": "Reward",
  "mode": "always-on",
  "status": "active",
  "rules": [
    {
      "id": "welcome_bonus",
      "trigger": "user_enrolled",
      "priority": 100,
      "conditions": [],
      "effects": [
        {
          "type": "award_badge",
          "badgeId": "welcome_badge"
        },
        {
          "type": "send_notification",
          "template": "welcome_message",
          "data": {
            "title": "Welcome to our loyalty program!",
            "message": "Complete 5 simple tasks to earn 500 bonus points"
          }
        }
      ]
    }
  ]
}

Referral Rewards

Process referral rewards when referred user enrolls:

// When user enrolls with referral
POST /v1/users/enroll
{
  "userId": "user_new",
  "email": "[email protected]",
  "referredBy": "user_referrer"
}

// Separately trigger referral reward for referrer
POST /v1/social/events
{
  "userId": "user_referrer",
  "eventType": "referral_completed",
  "eventData": {
    "referredUserId": "user_new",
    "referralStage": "enrolled"
  }
}

Best Practices

Use Enrollment Endpoint for New Users
- Simpler than manual user creation + transaction + event
- Atomic operation ensures consistency
- Automatic event triggering
Configure Welcome Bonuses Strategically
- Test different bonus amounts for conversion
- Higher bonuses for referred users
- Tier bonuses for premium sources
Track Enrollment Sources
- Use source field for attribution
- Analyze conversion by channel
- A/B test different sources
Leverage Next Steps
- Display in UI to guide users
- Track completion rates
- Optimize onboarding funnel
Monitor Enrollment Events
- Track user_enrolled event processing
- Ensure welcome campaigns trigger
- Check transaction creation

Create User - Manual user creation
Campaigns API - Create welcome campaigns
Transactions API - Track rewards
Social Events - Trigger campaigns

Support

For questions about enrollment:

Documentation: https://products.monterosa.co/mic/reference
Support: [email protected]

Last updated 26 days ago

Overview

Endpoint

Enroll User

Example Requests

Basic Enrollment

Enrollment with Referral

Custom Welcome Bonus

Response

Success Response (201 Created)

Error Responses

What Happens During Enrollment

Integration Patterns

Frontend Integration

Backend Integration

Onboarding Flow Example

Campaign Integration

Referral Rewards

Best Practices

Related Endpoints

Support