MegaRewards API Integration Guide

Welcome to the MegaRewards API integration guide. This guide provides detailed instructions for integrating with our rewards platform.

Getting Started

Prerequisites

Before you begin integrating with the MegaRewards API, you’ll need:

1. A MegaRewards account with API access
2. Your API key and placement IDs
3. Basic understanding of RESTful APIs and JSON

Integration Flow

The typical integration flow includes:

1. User Identification: Send user information to the API
2. Question Handling: Display and collect answers to qualification questions if required
3. Reward Delivery: Show available rewards to users
4. Tracking: Capture impressions and entries

API Endpoints

Base URL

All API requests should be made to:

https://api.megarewards.co

Authentication

Ensure you are using a placement ID in the rewards request.

Retrieving Rewards

To fetch available rewards for a user:

Endpoint: POST /v1/rewards

Required Header: Content-Type: application/json

Request body:

{
  "placement_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "user_ip": "123.123.123.123",
  "device_type": "ios",
  "identifiers": {
    "app_user_id": "user123"
  },
  "attributes": {
    "gender": "male",
    "age": 32,
    "spender_profile": "spender"
  },
  "image_size": "x2"
}

User Attributes Explained:

• gender: User’s gender for demographic targeting (male, female, not_specified)
• age: User’s age for age-based targeting and compliance (1-125)
• spender_profile: User’s spending behavior classification:
  • "spender": Users who have made purchases in the past
  • "non_spender": Users who have not made purchases
  • Used for reward targeting based on spending behavior

The image_size parameter is optional and controls the size of reward images returned. Available sizes:

• x1: Small size (150×88 pixels)
• x2: Medium size (300×175 pixels) - Default if not specified
• x3: Large size (600×350 pixels)
• x4: Extra large size (1200×700 pixels)

Response:

{
  "rewards": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "entry_url": "https://entry.example.com/reward/123",
      "impression_url": "https://impression.example.com/reward/123",
      "creative": {
        "rectangle_image_url": "https://example.com/images/reward.jpg",
        "logo_background_color": "#FFFFFF",
        "offer_text": "Get $5 for completing this offer!",
        "description_text": "Simple steps to earn your reward",
        "button_text": "Start Now",
        "disclaimer_text": "Terms and conditions apply"
      }
    }
  ]
}

Handling User Questions

Some rewards require additional user information. When this happens, the API will return a 202 status with questions that need to be answered:

{
  "rewards": [],
  "questions": [
    {
      "id": 1,
      "text": "What is your gender?",
      "answer_type": "single_choice",
      "answer_data_type": "string",
      "options": {
        "values": [
          {"name": "Male", "value": "male"},
          {"name": "Female", "value": "female"},
          {"name": "Prefer not to say", "value": "not_specified"}
        ]
      }
    },
    {
      "id": 2,
      "text": "What is your age?",
      "answer_type": "text",
      "answer_data_type": "number",
      "options": {
        "validation": {
          "min_number_value": 1,
          "max_number_value": 125
        }
      }
    },
    {
      "id": 3,
      "text": "Spender Profile",
      "answer_type": "single_choice",
      "answer_data_type": "string",
      "options": {
        "values": [
          {"name": "Non-Spender", "value": "non_spender"},
          {"name": "Spender", "value": "spender"}
        ]
      }
    }
  ]
}

After collecting the answers, include them in the user attributes in your next request.

Reward Targeting

Rewards can be targeted based on user attributes:

• Demographic Targeting: Age and gender-based targeting
• Behavioral Targeting: Spender profile targeting (spender vs non-spender)
• Geographic Targeting: Country and region-based targeting
• Device Targeting: iOS, Android, or web-specific rewards

The system automatically matches user attributes against reward targeting criteria to show the most relevant offers.

Revenue Event Webhooks

MegaRewards can notify your system when revenue is attributed to your users. This allows you to track earnings in real-time and take appropriate actions in your application.

Configuration

To enable revenue webhooks:

1. Provide your webhook URL to your MegaRewards contact
2. Choose your webhook method: POST (batch requests) or GET (individual requests)
3. Configure the webhook interval (default: 5 minutes, can be set from 1-60 minutes)
4. Enable revenue webhooks for your app

Webhook Signature Verification

If a webhook secret is configured for your app, all outbound webhook requests will include an X-MegaRewards-Signature header containing an HMAC-SHA256 hex digest.

POST webhooks: the signature is computed over the raw JSON body.

GET webhooks: the signature is computed over the full URL before the &sig= parameter is appended. The same signature value is also appended as &sig=<hex_digest> for integrators who cannot inspect request headers.

If no secret is configured, webhooks are sent without any signature.

POST Webhook Format

For POST webhooks, MegaRewards will send batch requests to your configured URL:

HTTP Method: POST
Content-Type: application/json

Request Body Example:

{
  "data": [
    {
      "app_user_id": "your-app-user-123",
      "idfa": "12345678-1234-1234-1234-123456789012",
      "gaid": "87654321-4321-4321-4321-210987654321",
      "email": "[email protected]",
      "phone": "+1555000000",
      "age": 32,
      "gender": "male",
      "revenue_transactions": [
        {
          "publisher_revenue_usd": 2.50,
          "transaction_id": "your-transaction-id-123",
          "conversion_event_id": "your-conversion-event-456",
          "conversion_event_timestamp": "2025-05-29T14:30:00Z",
          "conversion_event_name": "signup",
          "placement_id": "11111111-2222-3333-4444-555555555555",
          "placement_name": "Home Screen Offerwall"
        },
        {
          "publisher_revenue_usd": 1.75,
          "transaction_id": "your-transaction-id-789",
          "conversion_event_id": "your-conversion-event-012",
          "conversion_event_timestamp": "2025-05-29T14:35:00Z",
          "conversion_event_name": "purchase",
          "placement_id": "11111111-2222-3333-4444-555555555555",
          "placement_name": "Home Screen Offerwall"
        }
      ]
    }
  ],
  "count": 1
}

GET Webhook Format

For GET webhooks, MegaRewards will make individual HTTP GET requests for each revenue transaction using URL templates with placeholders:

HTTP Method: GET

URL Template Format: Configure your webhook URL with placeholders that will be replaced with actual values.

Example URL Template: https://your-domain.com/webhook?user_id={app_user_id}&revenue={publisher_revenue_usd}&tx_id={transaction_id}&event_id={conversion_event_id}&timestamp={conversion_event_timestamp}&age={age}&gender={gender}

Example Generated Request: GET https://your-domain.com/webhook?user_id=user_abc123&revenue=2.75&tx_id=tx_456789&event_id=evt_789012&timestamp=2025-01-15T10:30:00Z&age=28&gender=male

Available Placeholders:

• {app_user_id}: External app user ID
• {publisher_revenue_usd}: Publisher’s revenue in USD
• {transaction_id}: Unique transaction identifier
• {conversion_event_id}: Conversion event identifier
• {conversion_event_timestamp}: ISO8601 timestamp
• {conversion_event_name}: Event name for CPE offers
• {placement_id}: Placement UUID identifier
• {placement_name}: Placement name
• {age}: User age (if available)
• {gender}: User gender (if available)
• {idfa}: iOS identifier for advertisers (if available)
• {gaid}: Google advertising ID (if available)
• {email}: User email address (if available)
• {phone}: User phone number (if available)

Note: Only placeholders for data that exist will be replaced. Missing data will result in empty placeholder values.

Webhook Revenue Event Details

• POST Webhooks: Send JSON batches to your endpoint with revenue data arrays
• GET Webhooks: Make individual requests using URL templates with placeholders
• Payload Structure: Webhook data contains user identifiers and revenue transactions
• Batching: Webhooks are sent in batches with timing control to prevent server overload
• Identifiers: Only identifiers that exist for the user will be included (app_user_id, idfa, gaid, email, phone)
• User Attributes: Additional user data when available (age, gender)
• Revenue Transactions: Each transaction includes:
  • publisher_revenue_usd: Publisher’s revenue in USD
  • transaction_id: Unique identifier for this transaction
  • conversion_event_id: Identifier for the conversion event that generated this revenue
  • conversion_event_timestamp: ISO8601 formatted timestamp when the revenue was attributed
• Frequency: Based on your configured interval
• Retries: Failed webhooks will be retried with exponential backoff

Expected Response

Your webhook endpoint should return a 2xx status code to indicate successful receipt. Any other status code will be considered a failure.

Common Issues

Rate Limiting

The API enforces rate limits of 100 requests per minute per API key. If you exceed this limit, you’ll receive a 429 response.

Error Handling

All API errors include a descriptive message and appropriate HTTP status code.

Support

For additional assistance, contact our support team at [email protected] or open a ticket in your dashboard.