Pool Tournament REST API Documentation

This document provides comprehensive information about the Pool Tournament REST API endpoints for updating scores and searching matchups using metadata matching.

Overview

These endpoints provide flexible ways to interact with pool tournaments by leveraging a metadata matching system. Instead of requiring exact IDs, you can use metadata to identify matchups and users, making it easier to integrate with external systems.

💡 Learn about setting Lucra user metadata here

Authentication: All endpoints require an API key passed via the X-Lucra-Api-Key header (not as a query parameter).

Both endpoints support:

Direct ID lookup (fastest)
Metadata-based fuzzy matching (flexible)
Game and location filtering

Quick Start with cURL

Ready-to-use cURL examples for the sandbox environment. Simply replace YOUR_API_KEY_HERE with your actual API key.

Update User Score

curl -X POST https://api.sandbox.lucrasports.com/api/rest/pool-tournament/user-score \
  -H "X-Lucra-Api-Key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "object": {
      "matchupMetadata": {
        "externalId": "tournament-123"
      },
      "userScore": {
        "phoneNumber": "+1234567890",
        "score": 1850,
        "attemptFinished": true
      }
    }
  }'

Search for Matchups

curl -X POST https://api.sandbox.lucrasports.com/api/rest/pool-tournament/query \
  -H "X-Lucra-Api-Key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "object": {
      "matchupMetadata": {
        "externalId": "tournament-123"
      },
      "phoneNumber": "+1234567890"
    }
  }'

Using Direct IDs (Fastest)

# Update score using matchup ID and user ID
curl -X POST https://api.sandbox.lucrasports.com/api/rest/pool-tournament/user-score \
  -H "X-Lucra-Api-Key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "object": {
      "matchupId": "123e4567-e89b-12d3-a456-426614174000",
      "userScore": {
        "userId": "987fcdeb-51a2-43d7-9876-543210987654",
        "score": 2500,
        "attemptFinished": true
      }
    }
  }'

Using Game ID and Location

# Update scores for all matchups of a specific game at a location
curl -X POST https://api.sandbox.lucrasports.com/api/rest/pool-tournament/user-score \
  -H "X-Lucra-Api-Key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "object": {
      "gameId": "DARTS",
      "locationId": "123e4567-e89b-12d3-a456-426614174000",
      "userScore": {
        "userMetadata": {
          "externalId": "player-456"
        },
        "score": 3200,
        "attemptFinished": true
      }
    }
  }'

Metadata Matching System

The metadata matching system scores records based on how well their metadata matches your search criteria.

Important: Only records with a similarity score greater or equal than 1.0 are returned. This means at least one field must have an exact match, or multiple fields must have partial matches that sum to more than 1.0.

How Matching Works

The system evaluates matches using a scoring algorithm with the following rules:

1. Reserved Field: `externalId` (Highest Priority)

If your search metadata includes the externalId field, it takes absolute precedence over all other fields:

Behavior:

When externalId is present in the search, only exact matches are returned (score: 1)
If externalId doesn't match exactly, the record is excluded (score: 0)
No other fields are evaluated when externalId is present

Use Case: This is ideal when you're syncing data from external systems and need deterministic, exact matching.

2. Regular Field Matching

When externalId is not present, the system scores based on field similarity:

Match Type

Weight

Description

Exact Match

1.0

Field values are identical

Partial String Match

0.5

Search string is contained within record string (case-insensitive)

Array Intersection

0.7

Proportional to overlapping elements (e.g., 2 of 3 = 0.47)

Nested Object

0.8 × nested_score

Recursive matching with reduced weight

3. Supported Data Types

Strings: Case-insensitive partial matching
Numbers: Exact value comparison
Arrays: Intersection-based scoring
Objects: Recursive metadata matching
Booleans: Exact match only

4. Examples

Example 1: Reserved Field Match (externalId)

// Search metadata
{
  "externalId": "tournament-abc123",
  "level": 10
}

// Record metadata
{
  "externalId": "tournament-abc123",
  "level": 5,
  "region": "us-west"
}

// Result: MATCH (score: 1)
// Note: "level" mismatch is ignored because externalId matched

Example 2: String Match

// Search metadata
{
  "teamName": "Golden State Warriors"
}

// Record metadata
{
  "teamName": "Golden State Warriors"
}

// Result: MATCH (score: 1)

Example 3: Array Intersection

// Search metadata
{
  "tags": ["competitive", "ranked", "team"]
}

// Record metadata
{
  "tags": ["competitive", "ranked", "team"]
}

// Result: MATCH (score: 1)

Example 4: Combined Matching

// Search metadata
{
  "tournament": "summer-league",
  "skill_level": 7,
  "tags": ["pro", "ranked"]
}

// Record metadata
{
  "tournament": "summer-league",
  "skill_level": 7,
  "tags": ["pro"],
  "region": "NA"
}

// Result: MATCH (score: 2.35)
// Calculation:
//   - tournament exact match: 1.0
//   - skill_level exact match: 1.0
//   - tags intersection (1/2): 0.7 × 0.5 = 0.35
//   Total: 2.35

Example 5: Below Minimum Threshold (Not Returned)

// Search metadata
{
  "tournament": "summer-league",
  "region": "EU",
  "skill_level": 10
}

// Record metadata
{
  "tournament": "summer-tournament",  // Partial match
  "region": "NA",                     // No match
  "skill_level": 5                    // No match
}

// Result: NO MATCH (score: 0.5)
// Calculation:
//   - tournament partial match: 0.5
//   - region no match: 0
//   - skill_level no match: 0
//   Total: 0.5 (below minimum threshold of 1.0, record excluded)

Endpoints

Update User Scores with Matching

Updates scores for users in tournaments by matching both the matchup and user using metadata.

Endpoint: POST /pool-tournament/user-score

Authentication: Pass API key via X-Lucra-Api-Key header

⚠️ Important Behavior:

Scores will be applied to ALL matchups that match your criteria AND where the identified user is a participant
If your criteria match 5 tournaments and the user is participating in all 5, their score will be updated in all 5 tournaments
Use specific criteria (like externalId or direct matchupId) if you intend to update only a single matchup

Request Headers

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

Request Payload

{
  "object": {
    // Matchup Identifiers (at least one required)
    "matchupId": "uuid-string", // Optional: Direct matchup ID
    "matchupMetadata": {
      // Optional: Metadata to match matchup
      "tournament": "summer-league",
      "division": "pro"
    },
    "gameId": "game-123", // Optional: Filter by game
    "locationId": "uuid-string", // Optional: Filter by location

    // User Score Information (required)
    "userScore": {
      // User Identifiers (one required)
      "userId": "uuid-string", // Optional: Direct user ID
      "phoneNumber": "+1234567890", // Optional: User's phone number
      "userMetadata": {
        // Optional: Metadata to match user
        "externalId": "player-456",
        "username": "pro_player"
      },

      // Score Information (required)
      "score": 1250, // Required: User's score
      "metadata": {
        // Optional: Additional score metadata
        "accuracy": 0.85,
        "kills": 15
      },
      "attemptFinished": true // Optional: Whether attempt is complete
    }
  }
}

Field Descriptions

Matchup Identifiers (at least one required):

matchupId: Directly specify the matchup UUID (fastest, most precise)
matchupMetadata: JSON object to match against matchup metadata using similarity scoring
gameId: Filter matchups by game identifier
locationId: Filter matchups by location UUID

User Identifiers (one required):

userId: Directly specify the user UUID (fastest, most precise)
phoneNumber: User's phone number (exact match required)
userMetadata: JSON object to match against user metadata using similarity scoring

Score Information:

score: (required) Numeric score value
metadata: (optional) Additional JSON metadata about this score
attemptFinished: (optional) Boolean indicating if the attempt is complete

Matching Priority

The system searches for matchups using combined criteria:

matchupId (if provided) - Returns immediately
matchupMetadata + gameId + locationId (if all/either provided) - Searches using similarity scoring and combined criteria

For users:

userId (if provided) - Returns immediately
phoneNumber (if provided) - Exact match lookup
userMetadata (if provided) - Searches using similarity scoring

Response

Success Response (200):

{
  "status": "success",
  "data": {
    "affectedMatchupIds": ["uuid-1", "uuid-2"],
    "failedMatchupIds": []
  }
}

Response Fields:

status: Always "success" for successful requests
data.affectedMatchupIds: Array of matchup UUIDs where scores were successfully updated
data.failedMatchupIds: Array of matchup UUIDs where score updates failed

Example Success Response (Multiple Matchups Updated):

{
  "status": "success",
  "data": {
    "affectedMatchupIds": [
      "123e4567-e89b-12d3-a456-426614174000",
      "987fcdeb-51a2-43d7-9876-543210987654",
      "456789ab-cdef-0123-4567-89abcdef0123"
    ],
    "failedMatchupIds": []
  }
}

Example Partial Failure Response:

{
  "status": "success",
  "data": {
    "affectedMatchupIds": ["123e4567-e89b-12d3-a456-426614174000", "987fcdeb-51a2-43d7-9876-543210987654"],
    "failedMatchupIds": ["456789ab-cdef-0123-4567-89abcdef0123"]
  }
}

Example Error Response (Matchup Not Found):

{
  "status": "failure",
  "error": "Matchup not found"
}

Example Error Response (Missing Identifiers):

{
  "status": "failure",
  "error": "No matchup identifiers were provided"
}

Example Error Response (User Not Found):

{
  "status": "failure",
  "error": "User not found"
}

Example Requests

Example 1: Update by Direct IDs

{
  "object": {
    "matchupId": "123e4567-e89b-12d3-a456-426614174000",
    "userScore": {
      "userId": "987fcdeb-51a2-43d7-9876-543210987654",
      "score": 2500,
      "attemptFinished": true
    }
  }
}

Example 2: Update by Metadata (Single Matchup)

{
  "object": {
    "matchupMetadata": {
      "externalId": "tournament-123"
    },
    "userScore": {
      "userMetadata": {
        "externalId": "player-789"
      },
      "score": 1800,
      "metadata": {
        "completion_time": 300,
        "accuracy": 0.92
      }
    }
  }
}

Example 3: Update by Phone Number

{
  "object": {
    "matchupMetadata": {
      "externalId": "matchup-1"
    },
    "userScore": {
      "phoneNumber": "+1234567890",
      "score": 185
    }
  }
}

Example 4: Update Multiple Matchups by Game and Location

{
  "object": {
    "gameId": "fortnite-ranked",
    "locationId": "123e4567-e89b-12d3-a456-426614174000",
    "userScore": {
      "userMetadata": {
        "username": "pro_player_01",
        "region": "NA"
      },
      "score": 3200,
      "attemptFinished": true
    }
  }
}

Example 5: Complex Metadata Matching

{
  "object": {
    "matchupMetadata": {
      "season": "2024-spring",
      "division": "diamond",
      "game_mode": "ranked-doubles"
    },
    "gameId": "rocket-league",
    "userScore": {
      "userMetadata": {
        "team": "blue-squad",
        "rank": "diamond-3",
        "tags": ["competitive", "verified"]
      },
      "score": 1650,
      "metadata": {
        "goals": 5,
        "assists": 3,
        "saves": 8
      }
    }
  }
}

Processing Flow

Validation: Request is validated against schema
API Key Verification: Tenant is identified from X-Lucra-Api-Key header
Matchup Matching: System finds all matchups matching your criteria (score >= 1.0) using combined filters
User Matching: System identifies the user from userId, phoneNumber, or userMetadata (score >= 1.0)
Participation Filter: System filters matchups to only those where the user is a participant
Score Updates: Scores are updated for ALL filtered matchups in parallel
Logging: All ingestion attempts are logged for auditing and debugging
Response: Returns lists of successful and failed matchup IDs

Example: If you search by gameId: "rocket-league" and there are 10 active Rocket League tournaments where user "player-123" is participating, the score will be updated in all 10 tournaments.

Search User Matchups by Metadata

Searches for matchups that a user is participating in, using flexible metadata matching.

Endpoint: POST /pool-tournament/query

Authentication: Pass API key via X-Lucra-Api-Key header

Note: Only returns matchups with a metadata similarity score greater or equal than 1.0. If user identifiers are provided, only matchups where the user is a participant are returned.

Request Headers

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

Request Payload

{
  "object": {
    // Matchup Identifiers (at least one required)
    "matchupId": "uuid-string", // Optional: Direct matchup ID
    "matchupMetadata": {
      // Optional: Metadata to match matchup
      "tournament": "summer-league",
      "division": "pro"
    },
    "gameId": "game-123", // Optional: Filter by game
    "locationId": "uuid-string", // Optional: Filter by location

    // User Identifiers (optional)
    "userId": "uuid-string", // Optional: Direct user ID
    "phoneNumber": "+1234567890", // Optional: User's phone number
    "userMetadata": {
      // Optional: Metadata to match user
      "externalId": "player-456",
      "username": "pro_player"
    }
  }
}

Field Descriptions

Matchup Identifiers (at least one required):

matchupId: Directly specify the matchup UUID
matchupMetadata: JSON object to match against matchup metadata
gameId: Filter matchups by game identifier
locationId: Filter matchups by location UUID

User Identifiers (optional):

userId: Filter for specific user UUID
phoneNumber: User's phone number (exact match required)
userMetadata: Match user by metadata

Note: If no user identifier (userId, phoneNumber, or userMetadata) is provided, the endpoint returns ALL matching matchups regardless of participants.

Response

Success Response (200):

{
  "status": "success",
  "data": ["matchup-uuid-1", "matchup-uuid-2", "matchup-uuid-3"]
}

Response Fields:

status: Always "success" for successful requests
data: Array of matchup UUIDs that match the search criteria

Example Success Response (Multiple Matchups Found):

{
  "status": "success",
  "data": ["123e4567-e89b-12d3-a456-426614174000", "987fcdeb-51a2-43d7-9876-543210987654"]
}

Example Success Response (No Matchups Found):

{
  "status": "success",
  "data": []
}

Example Error Response (User Not Found):

{
  "status": "failure",
  "error": "User not found"
}

Example Error Response (Missing Identifiers):

{
  "status": "failure",
  "error": "No matchup identifiers were provided"
}

Example Error Response (Matchup Not Found):

{
  "status": "failure",
  "error": "Matchup not found"
}

Example Requests

Example 1: Find User's Matchups by Direct IDs

{
  "object": {
    "gameId": "fortnite-ranked",
    "userId": "987fcdeb-51a2-43d7-9876-543210987654"
  }
}

Example 2: Find Matchups by Metadata (No User Filter)

{
  "object": {
    "matchupMetadata": {
      "tournament": "summer-championship",
      "bracket": "winners"
    }
  }
}

Example 3: Find User's Matchups by Metadata

{
  "object": {
    "matchupMetadata": {
      "season": "2024-Q1",
      "tier": "platinum"
    },
    "userMetadata": {
      "externalId": "steam-user-12345"
    }
  }
}

Example 4: Find Matchups by Phone Number

{
  "object": {
    "matchupMetadata": {
      "externalId": "matchup-1"
    },
    "phoneNumber": "+1234567890"
  }
}

Example 5: Complex Search with Multiple Filters

{
  "object": {
    "gameId": "apex-legends",
    "locationId": "123e4567-e89b-12d3-a456-426614174000",
    "matchupMetadata": {
      "mode": "battle-royale",
      "ranked": true,
      "region": "NA-East"
    },
    "userMetadata": {
      "username": "ttv_player",
      "verified": true
    }
  }
}

Processing Flow

Validation: Request is validated against schema
API Key Verification: Tenant is identified from X-Lucra-Api-Key header
Matchup Search: System finds matchups matching provided identifiers (score >= 1.0 for metadata matching) using combined filters
User Search (if provided): System identifies user from userId, phoneNumber, or userMetadata (score >= 1.0 for metadata matching)
Participation Filter (if user provided): Filters matchups to only those where the user is a participant
Response: Returns array of matching matchup UUIDs

Search Priority:

Matchups: matchupId → matchupMetadata + gameId + locationId (combined)
Users: userId → phoneNumber → userMetadata

Error Handling

Error Response Format

All errors follow this consistent format:

{
  "status": "failure",
  "error": "<error message>"
}

Common Errors

Error Message

Scenario

Resolution

"No matchup identifiers were provided"

No matchup identifier provided

Provide at least one of: matchupId, matchupMetadata, gameId, or locationId

"Matchup not found"

No matchups matched search criteria

Check your metadata values

"User not found"

No user matched search criteria

Verify user exists and identifiers are correct

"Invalid Api Key."

API key is invalid or expired

Check your API key configuration and header format

Validation errors (various)

Request payload validation failed

Check request structure matches schema (see examples below)

Example Error Responses

Missing Matchup Identifiers:

{
  "status": "failure",
  "error": "No matchup identifiers were provided"
}

Matchup Not Found:

{
  "status": "failure",
  "error": "Matchup not found"
}

User Not Found:

{
  "status": "failure",
  "error": "User not found"
}

Invalid API Key:

{
  "status": "failure",
  "error": "Invalid Api Key."
}

Validation Error Examples:

{
  "status": "failure",
  "error": "locationId must be a UUID"
}

{
  "status": "failure",
  "error": "gameID must be a String"
}

Handling Score Update Failures

When updating scores across multiple matchups, partial failures are possible. The response will still have status: "success" but will include failed matchup IDs:

{
  "status": "success",
  "data": {
    "affectedMatchupIds": ["uuid-1", "uuid-2"],
    "failedMatchupIds": ["uuid-3"]
  }
}

How to handle:

Check data.failedMatchupIds to identify which updates failed
Failed updates are logged with error details for debugging
You can retry failed updates individually using their specific matchup IDs

Best Practices

1. Use externalId for Deterministic Matching

When you need exact matches, use the externalId field in metadata:

{
  "matchupMetadata": {
    "externalId": "unique-tournament-id"
  }
}

This ensures only exact matches are returned, preventing unintended updates to similar matchups.

2. Prefer Direct IDs When Available

Direct IDs are faster and more precise:

// Good: Fast and precise
{
  "matchupId": "123e4567-e89b-12d3-a456-426614174000",
  "userScore": {
    "userId": "987fcdeb-51a2-43d7-9876-543210987654",
    "score": 2500
  }
}

// Also good: Flexible but slower
{
  "matchupMetadata": { "externalId": "tournament-123" },
  "userScore": {
    "userMetadata": { "externalId": "player-789" },
    "score": 2500
  }
}

3. Use Phone Number for Simple User Lookup

When you have the user's phone number, it's a straightforward way to identify them:

{
  "matchupMetadata": { "externalId": "tournament-123" },
  "userScore": {
    "phoneNumber": "+1234567890",
    "score": 1850
  }
}

4. Combine Identifiers for Precision

Layer multiple identifiers to narrow results:

{
  "gameId": "rocket-league",
  "locationId": "venue-uuid",
  "matchupMetadata": {
    "season": "2024-spring",
    "division": "diamond"
  }
}

Note: All provided criteria are evaluated together.

5. Structure Metadata Consistently

Maintain consistent metadata structure across your system:

// Good: Consistent structure
{
  "externalId": "player-123",
  "region": "NA",
  "rank": 15
}

// Avoid: Inconsistent structures
// User 1: { "externalId": "123" }
// User 2: { "external_id": "456" }  // Different key

6. Use Descriptive Metadata Keys

Choose metadata keys that are descriptive and unlikely to collide:

// Good
{
  "tournament_season": "2024-spring",
  "skill_division": "diamond-tier"
}

// Avoid
{
  "s": "2024-spring",  // Too generic
  "div": "diamond"     // Unclear
}

7. Test Metadata Matching First

Before updating scores, test your search criteria using the search endpoint:

# 1. First, test your search
POST /pool-tournament/query
{
  "object": {
    "matchupMetadata": { "tournament": "summer-2024" },
    "userMetadata": { "externalId": "player-123" }
  }
}

# 2. Verify results, then update scores
POST /pool-tournament/user-score
{
  "object": {
    "matchupMetadata": { "tournament": "summer-2024" },
    "userScore": {
      "userMetadata": { "externalId": "player-123" },
      "score": 2500
    }
  }
}

8. Understand Multiple Match Behavior

Critical: Metadata matching can return multiple results, and this behavior is different for updates vs. searches:

For Updates: Scores will be updated across ALL matchups where:
- The matchup matches your criteria (score >= 1.0)
- AND the user is a participant in that matchup
For Search: You'll receive ALL matchup IDs that match your criteria (score >= 1.0)

Example Scenario:

// Request
{
  "matchupMetadata": { "season": "2024-spring" },
  "userScore": {
    "userMetadata": { "username": "player123" },
    "score": 1500
  }
}

// If there are 3 tournaments with season="2024-spring"
// and player123 is participating in all 3,
// their score will be updated to 1500 in ALL 3 tournaments

To update only ONE matchup:

Use direct matchupId (most precise)
Use externalId in matchupMetadata (deterministic)
Combine multiple filters to narrow results (e.g., gameId + locationId + metadata)

9. Monitor Score Updates

All score update attempts are logged for auditing and debugging purposes. Contact your integration support team if you need to review historical update attempts or troubleshoot failed updates.

10. Rate Limiting and Performance

Use direct IDs for high-frequency operations
Metadata matching is more resource-intensive than ID lookups
Consider caching frequently accessed matchup/user IDs

Support

For issues or questions:

Check error messages and logs
Review this documentation
Verify your metadata structure
Verify API key is passed in the X-Lucra-Api-Key header
Test with the search endpoint first
Contact your integration support team

Last Updated: 2025-11-19 Version: 1.1

PreviousTournament Webhooks NextGames You Play REST API

Last updated 2 months ago

Good afternoon

hashtagTable of Contents

hashtagOverview

hashtagQuick Start with cURL

hashtagUpdate User Score

hashtagSearch for Matchups

hashtagUsing Direct IDs (Fastest)

hashtagUsing Game ID and Location

hashtagMetadata Matching System

hashtagHow Matching Works

hashtag1. Reserved Field: externalId (Highest Priority)

hashtag2. Regular Field Matching

hashtag3. Supported Data Types

hashtag4. Examples

hashtagEndpoints

hashtagUpdate User Scores with Matching

hashtagRequest Headers

hashtagRequest Payload

hashtagField Descriptions

hashtagMatching Priority

hashtagResponse

hashtagExample Requests

hashtagProcessing Flow

hashtagSearch User Matchups by Metadata

hashtagRequest Headers

hashtagRequest Payload

hashtagField Descriptions

hashtagResponse

hashtagExample Requests

hashtagProcessing Flow

hashtagError Handling

hashtagError Response Format

hashtagCommon Errors

hashtagExample Error Responses

hashtagHandling Score Update Failures

hashtagBest Practices

hashtag1. Use externalId for Deterministic Matching

hashtag2. Prefer Direct IDs When Available

hashtag3. Use Phone Number for Simple User Lookup

hashtag4. Combine Identifiers for Precision

hashtag5. Structure Metadata Consistently

hashtag6. Use Descriptive Metadata Keys

hashtag7. Test Metadata Matching First

hashtag8. Understand Multiple Match Behavior

hashtag9. Monitor Score Updates

hashtag10. Rate Limiting and Performance

hashtagSupport

Table of Contents

Overview

Quick Start with cURL

Update User Score

Search for Matchups

Using Direct IDs (Fastest)

Using Game ID and Location

Metadata Matching System

How Matching Works

1. Reserved Field: `externalId` (Highest Priority)

2. Regular Field Matching

3. Supported Data Types

4. Examples

Endpoints

Update User Scores with Matching

Request Headers

Request Payload

Field Descriptions

Matching Priority

Response

Example Requests

Processing Flow

Search User Matchups by Metadata

Request Headers

Request Payload

Field Descriptions

Response

Example Requests

Processing Flow

Error Handling

Error Response Format

Common Errors

Example Error Responses

Handling Score Update Failures

Best Practices

1. Use externalId for Deterministic Matching

2. Prefer Direct IDs When Available

3. Use Phone Number for Simple User Lookup

4. Combine Identifiers for Precision

5. Structure Metadata Consistently

6. Use Descriptive Metadata Keys

7. Test Metadata Matching First

8. Understand Multiple Match Behavior

9. Monitor Score Updates

10. Rate Limiting and Performance

Support