Social Tracking

The Social Tracking API allows you to reward users for social media actions like posting with hashtags, mentioning accounts, or commenting on specific posts.

Overview

Social tracking integrates seamlessly with the loyalty layer:

• Social actions trigger transactions (points, XP, coins)

• Rewards feed into tier progression automatically

• All tracked through existing campaigns and analytics

Social Rules API

List Social Rules

Get all social tracking rules for your organization.

Endpoint: GET /social/rules

Query Parameters:

Parameter	Type	Required	Description
platform	string	No	Filter by platform (twitter, instagram, facebook)
status	string	No	Filter by status (active, inactive)
limit	number	No	Number of results (default: 50)

Example Request:

curl -X GET "https://api.monterosa.cloud/loyalty/v1/social/rules?platform=twitter" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID"

Example Response:

{
  "success": true,
  "data": {
    "rules": [
      {
        "ruleId": "social_rule_abc123",
        "name": "Comment on MVP Post",
        "platform": "twitter",
        "type": "reply_to_post",
        "postId": "1844567890123456789",
        "effects": [
          {
            "type": "award_points",
            "params": { "amount": 25 }
          }
        ],
        "limits": {
          "maxPerUser": 1,
          "maxTotal": 1000,
          "startDate": "2025-10-05T00:00:00Z",
          "endDate": "2025-10-06T00:00:00Z"
        },
        "status": "active",
        "stats": {
          "totalTriggers": 456,
          "uniqueUsers": 234,
          "pointsAwarded": 11400
        }
      }
    ],
    "cursor": null
  }
}

Create Social Rule

Create a new social tracking rule.

Endpoint: POST /social/rules

Request Body:

Field	Type	Required	Description
name	string	Yes	Rule name
platform	string	Yes	Platform: twitter, instagram, facebook
type	string	Yes	Rule type (see below)
value	string	Conditional	Required for hashtag and mention types
postId	string	Conditional	Required for reply_to_post type
postUrl	string	Conditional	Alternative to postId
effects	array	Yes	Array of effects to trigger
campaignId	string	No	Link to campaign
limits	object	No	Usage limits
requirements	object	No	Additional requirements

Rule Types:

• hashtag - Track posts with specific hashtags

• mention - Track mentions of specific accounts

• reply_to_post - Track replies to a specific post

• share - Track shares/retweets

• like - Track likes on posts

• follow - Track new followers

Example Request (Reply to Post):

curl -X POST "https://api.monterosa.cloud/loyalty/v1/social/rules" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Comment on MVP Post",
    "platform": "twitter",
    "type": "reply_to_post",
    "postId": "1844567890123456789",
    "postUrl": "https://x.com/NBA/status/1844567890123456789",
    "requirements": {
      "minLength": 10,
      "preventDuplicates": true
    },
    "effects": [
      {
        "type": "award_points",
        "params": { "amount": 25 }
      }
    ],
    "limits": {
      "maxPerUser": 1,
      "maxTotal": 1000,
      "endDate": "2025-10-06T00:00:00Z"
    },
    "campaignId": "campaign-social-001"
  }'

Example Request (Hashtag):

curl -X POST "https://api.monterosa.cloud/loyalty/v1/social/rules" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Share with #NBAAllStar",
    "platform": "twitter",
    "type": "hashtag",
    "value": "#NBAAllStar",
    "effects": [
      {
        "type": "award_points",
        "params": { "amount": 50 }
      },
      {
        "type": "award_badge",
        "params": { "badgeId": "badge-social-advocate" }
      }
    ],
    "limits": {
      "maxPerUser": "daily"
    }
  }'

Social Events Webhook

Process Social Event

Webhook endpoint that receives social platform events and processes rewards.

Endpoint: POST /social/events

Note: This endpoint is called by social platform webhooks (Twitter, Instagram, etc.)

Request Body:

{
  "orgId": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "twitter",
  "event": "tweet.reply",
  "user": {
    "id": "twitter_123456",
    "handle": "@fan_user",
    "verified": true
  },
  "reply": {
    "id": "1844567890999999999",
    "text": "Lakers all the way! 🏆 #NBAFinals",
    "parentPostId": "1844567890123456789",
    "timestamp": "2025-10-05T14:30:00Z"
  },
  "hashtags": ["#NBAFinals"],
  "mentions": []
}

Response:

{
  "success": true,
  "data": {
    "matched": true,
    "userId": "user123",
    "rulesMatched": 1,
    "results": [
      {
        "ruleId": "social_rule_abc123",
        "ruleName": "Comment on MVP Post",
        "transactionId": "txn_xyz789",
        "pointsAwarded": 25
      }
    ]
  }
}

Social Mappings API

Create Social Mapping

Link a social media account to a loyalty user.

Endpoint: POST /social/mappings

Request Body:

Field	Type	Required	Description
userId	string	Yes	Loyalty system user ID
platform	string	Yes	Social platform
socialUserId	string	Yes	Platform-specific user ID
handle	string	No	Social media handle
verified	boolean	No	Account verified status

Example Request:

curl -X POST "https://api.monterosa.cloud/loyalty/v1/social/mappings" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user123",
    "platform": "twitter",
    "socialUserId": "twitter_123456",
    "handle": "@fan_user",
    "verified": true
  }'

Example Response:

{
  "success": true,
  "data": {
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "twitter:twitter_123456",
    "userId": "user123",
    "platform": "twitter",
    "handle": "@fan_user",
    "verified": true,
    "createdAt": "2025-10-05T18:00:00.000Z"
  }
}

Integration with Loyalty Layer

Social tracking seamlessly integrates with existing loyalty concepts:

1. Transactions Created Automatically

When a social rule matches, a transaction is automatically created:

{
  "transactionId": "txn_xyz789",
  "userId": "user123",
  "type": "points",
  "amount": 25,
  "reason": "Comment on MVP Post",
  "campaignId": "campaign-social-001",
  "ruleId": "social_rule_abc123",
  "metadata": {
    "source": "social_tracking",
    "platform": "twitter",
    "eventType": "tweet.reply",
    "socialPostId": "1844567890999999999"
  }
}

2. Contributes to Tier Progression

Points from social actions count toward tier upgrades automatically.

3. Visible in Analytics

GET /v1/analytics
# Shows social engagement transactions
# Includes top campaigns (social campaigns)
# Tracks users engaging via social

Use Cases

Comment on Specific Post

Drive engagement on important posts:

// Admin creates rule
POST /v1/social/rules
{
  "name": "Comment on Finals Prediction",
  "platform": "twitter",
  "type": "reply_to_post",
  "postUrl": "https://x.com/NBA/status/123...",
  "effects": [{ "type": "award_points", "params": { "amount": 25 }}],
  "limits": { "maxPerUser": 1, "maxTotal": 500 }
}

// User comments on post
// Webhook triggers: POST /v1/social/events
// Transaction created automatically
// User sees: "+25 points earned for engaging with @NBA!"

Share with Hashtag Campaign

Viral hashtag campaigns:

// Rule: Share with #NBAAllStar
POST /v1/social/rules
{
  "type": "hashtag",
  "value": "#NBAAllStar",
  "effects": [
    { "type": "award_points", "params": { "amount": 50 }},
    { "type": "award_badge", "params": { "badgeId": "social-advocate" }}
  ]
}

// Users share content with hashtag
// Automatically earn 50 points + badge

Account Mention Rewards

Reward users for mentioning your brand:

POST /v1/social/rules
{
  "type": "mention",
  "value": "@NBA",
  "effects": [{ "type": "award_points", "params": { "amount": 25 }}],
  "limits": { "maxPerUser": "daily" }
}

Error Responses

400 Bad Request:

{
  "success": false,
  "error": {
    "message": "Validation failed",
    "details": {
      "errors": [
        "platform must be one of: twitter, instagram, facebook",
        "effects array is required and must contain at least one effect"
      ]
    }
  }
}

409 Conflict:

{
  "success": false,
  "error": {
    "message": "Social mapping already exists"
  }
}

Best Practices

1. Link Accounts Early: Encourage users to link social accounts during onboarding

2. Clear Communication: Tell users how to earn rewards via social actions

3. Set Limits: Prevent abuse with per-user and total limits

4. Verify Actions: Check for bot/spam activity before awarding

5. Time-Bound Rules: Use endDate for campaign-specific rules

6. Track Performance: Monitor rule stats to optimize rewards

7. Multiple Effects: Combine points + badges for maximum engagement