Free-to-Play REST API

Overview

The Free-to-Play (FTP) REST API is primarily event-driven through webhooks, with minimal direct REST endpoints. Game lifecycle events are delivered via webhooks (see Free-to-Play Webhooks), while the REST API handles reward fulfillment tracking.

Prerequisites

• API key configured per API Setup

• Webhook subscriptions configured per Webhook Setup

• Understanding of FTP game types and reward structures

Base URL

Sandbox: https://api.sandbox.lucrasports.com
Production: https://api.lucrasports.com

Authentication

All requests require authentication via the X-Lucra-Api-Key header. See API Setup for details.

Game Types

Free-to-Play games support three matchup types:

Type	Description
PROFESSIONAL_SPORTS_TEAM_STAT	Team-based sports statistics
PROFESSIONAL_SPORTS_PLAYER_STAT	Individual player statistics
RECREATIONAL_GAME	Free-to-play recreational games

Endpoints

Mark User Reward as Redeemed

Record when a user has successfully claimed their Free-to-Play reward.

POST /api/rest/user_redeemed_tenant_reward
X-Lucra-Api-Key: <your-api-key>
Content-Type: application/json

Request Body:

{
  "event": "UserRewardRedeemed",
  "matchupId": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "redeemedAt": "2025-06-15T14:30:00Z"
}

Field Descriptions:

Field	Type	Required	Description
event	string	Yes	Always "UserRewardRedeemed"
matchupId	string	Yes	UUID of the completed matchup
userId	string	Yes	UUID of the user redeeming reward
redeemedAt	string	No	ISO 8601 timestamp (defaults to current time if omitted)

Response:

{
  "OK": true
}

Use Cases:

• Track reward fulfillment completion

• Prevent duplicate reward claims

• Audit reward distribution

• Trigger follow-up actions after redemption

Example Implementation:

async function markRewardRedeemed(matchupId: string, userId: string, apiKey: string) {
  const response = await fetch('https://api.lucrasports.com/api/rest/user_redeemed_tenant_reward', {
    method: 'POST',
    headers: {
      'X-Lucra-Api-Key': apiKey,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      event: 'UserRewardRedeemed',
      matchupId,
      userId,
      redeemedAt: new Date().toISOString(),
    }),
  });

  const result = await response.json();
  return result.OK;
}

Free-to-Play Game Flow

Free-to-Play games are primarily managed through webhooks rather than direct API calls:

1. Game Created → FtpMatchupCreated webhook
2. User Accepts → FtpMatchupAccepted webhook
3. Game Completes → ContestUserOutcome webhook (per participant)
4. Reward Fulfillment → Your system grants reward
5. Redemption Tracking → POST /user_redeemed_tenant_reward

Webhook-Driven Operations

Unlike standard Games You Play games, FTP games rely on webhooks for state changes:

Operation	Method
Game Creation	Webhook: FtpMatchupCreated
User Acceptance	Webhook: FtpMatchupAccepted
Game Completion	Webhook: ContestUserOutcome
Reward Redemption	REST: POST /user_redeemed_tenant_reward

Reward Types

Free-to-Play games use tenant-specific rewards rather than cash payouts:

{
  "reward": {
    "tenantRewardId": "reward-uuid",
    "intentId": "custom-intent-identifier",
    "metadata": {
      "rewardType": "discount",
      "value": "10",
      "expiresAt": "2025-12-31T23:59:59Z"
    }
  }
}

Reward Fields:

• tenantRewardId - Your reward identifier

• intentId - Custom tracking identifier

• metadata - Arbitrary reward details (structure defined by you)

Integration Pattern

1. Webhook Reception

Receive ContestUserOutcome webhook when game completes:

{
  "event": "ContestUserOutcome",
  "matchupId": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "user-uuid",
  "outcomes": [
    {
      "userId": "user-uuid",
      "result": "WIN",
      "reward": {
        "tenantRewardId": "reward-123",
        "intentId": "promo-2025-q2",
        "metadata": {...}
      }
    }
  ]
}

2. Reward Fulfillment

Grant the reward in your system:

async function handleContestOutcome(webhook: ContestUserOutcomeWebhook) {
  const { matchupId, userId, outcomes } = webhook;

  // Find user's outcome
  const userOutcome = outcomes.find((o) => o.userId === userId);

  if (userOutcome?.result === 'WIN' && userOutcome.reward) {
    // Grant reward in your system
    await grantReward(userId, userOutcome.reward);

    // Notify Lucra of redemption
    await markRewardRedeemed(matchupId, userId, apiKey);
  }
}

3. Redemption Tracking

After successfully granting the reward, notify Lucra:

await fetch('https://api.lucrasports.com/api/rest/user_redeemed_tenant_reward', {
  method: 'POST',
  headers: {
    'X-Lucra-Api-Key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    event: 'UserRewardRedeemed',
    matchupId: webhook.matchupId,
    userId: webhook.userId,
  }),
});

Error Handling

Status	Meaning
200	Success - Reward redemption recorded
400	Bad Request - Invalid parameters or missing required fields
401	Unauthorized - Invalid or missing API key
404	Not Found - Matchup or user not found
500	Internal Server Error

Best Practices

Idempotent Redemption

Track redemptions to prevent duplicate reward grants:

interface RedemptionRecord {
  matchupId: string;
  userId: string;
  redeemedAt: Date;
  rewardDetails: any;
}

async function safelyRedeemReward(matchupId: string, userId: string, reward: any) {
  // Check if already redeemed
  const existing = await db.redemptions.findOne({ matchupId, userId });

  if (existing) {
    console.log(`Reward already redeemed for ${userId} in ${matchupId}`);
    return existing;
  }

  // Grant reward
  await grantReward(userId, reward);

  // Record redemption
  const record = await db.redemptions.create({
    matchupId,
    userId,
    redeemedAt: new Date(),
    rewardDetails: reward,
  });

  // Notify Lucra
  await markRewardRedeemed(matchupId, userId, apiKey);

  return record;
}

Reward Metadata Structure

Define a consistent metadata schema for your rewards:

interface RewardMetadata {
  type: 'discount' | 'bonus_credits' | 'free_item' | 'multiplier';
  value: string;
  expiresAt?: string;
  conditions?: {
    minimumPurchase?: number;
    applicableCategories?: string[];
  };
  displayText?: string;
}

// Example reward
const reward = {
  tenantRewardId: 'reward-123',
  intentId: 'summer-promo-2025',
  metadata: {
    type: 'discount',
    value: '15',
    expiresAt: '2025-08-31T23:59:59Z',
    conditions: {
      minimumPurchase: 50,
    },
    displayText: '15% off your next purchase of $50 or more',
  } as RewardMetadata,
};

Error Recovery

Handle failures gracefully with retry logic:

async function markRewardRedeemedWithRetry(matchupId: string, userId: string, maxRetries: number = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      await markRewardRedeemed(matchupId, userId, apiKey);
      return true;
    } catch (error) {
      if (attempt === maxRetries - 1) {
        // Log for manual reconciliation
        await logFailedRedemption(matchupId, userId, error);
        return false;
      }
      // Exponential backoff
      await sleep(Math.pow(2, attempt) * 1000);
    }
  }
}

Webhook Correlation

Correlate redemption with original webhook delivery:

async function handleContestOutcome(webhook: ContestUserOutcomeWebhook) {
  const webhookId = generateWebhookId(webhook);

  try {
    // Process outcome
    await processOutcome(webhook);

    // Track webhook processing
    await db.webhookLog.create({
      webhookId,
      event: 'ContestUserOutcome',
      matchupId: webhook.matchupId,
      userId: webhook.userId,
      processedAt: new Date(),
    });
  } catch (error) {
    await db.webhookLog.create({
      webhookId,
      event: 'ContestUserOutcome',
      matchupId: webhook.matchupId,
      error: error.message,
      failedAt: new Date(),
    });
    throw error;
  }
}

Related Documentation

• Free-to-Play Webhooks - Webhook events for FTP games

• Webhook Setup - Configure webhook subscriptions

• Games You Play REST API - Standard GYP game endpoints

• API Setup - Authentication configuration