---
updatedAt: 2026-05-19T09:14:46.000Z
agentTools:
  projectIndex: https://developer.optimove.com/llms.txt
---

# Enroll a Player in a Tournament

Enrollment applies to tournament-type leaderboards only. Calling this on a regular leaderboard returns `400 "Only tournaments require enrollment"`.

If `costAmount` is non-null in the response, re-fetch `GET /player-rewards/brand/{brandId}/player/{playerId}` so the player's balance reflects the entry fee.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Optimove Loyalty System API",
    "version": "1.0.0",
    "description": "Public API for building custom Loyalty widget frontends on top of Optimove's Loyalty System.\n\nUse these endpoints to fetch brand configuration, player progress, missions, rewards, badges, and leaderboards, and to drive player actions like claiming mission rewards and enrolling in tournaments.\n\n> 📘 Authentication\n>\n> Authentication is not yet enforced on widget endpoints. No token is required at this time. Token-based auth will be added in a future release. When it ships, request headers and the widget initialization flow will change, and this reference will be updated.\n\n> 🚧 CORS\n>\n> Requests from certain origins are permitted by default. If your widget runs on a domain outside that set, contact the Optimove team to have it added before starting development.",
    "contact": {
      "name": "Optimove Support",
      "url": "https://www.optimove.com/support"
    }
  },
  "servers": [
    {
      "url": "https://opti-ls-api-us.optimove.net/api",
      "description": "Production (US)"
    },
    {
      "url": "https://opti-ls-api-eu.optimove.net/api",
      "description": "Production (EU)"
    }
  ],
  "tags": [
    {
      "name": "Leaderboards",
      "description": "Leaderboards and tournaments configured for the brand, plus enrollment endpoints."
    }
  ],
  "paths": {
    "/leaderboards/{brandId}/{leaderboardId}/enroll/{playerId}": {
      "post": {
        "tags": [
          "Leaderboards"
        ],
        "operationId": "enrollInTournament",
        "summary": "Enroll a Player in a Tournament",
        "description": "Enrollment applies to tournament-type leaderboards only. Calling this on a regular leaderboard returns `400 \"Only tournaments require enrollment\"`.\n\nIf `costAmount` is non-null in the response, re-fetch `GET /player-rewards/brand/{brandId}/player/{playerId}` so the player's balance reflects the entry fee.",
        "parameters": [
          {
            "$ref": "#/components/parameters/BrandId"
          },
          {
            "$ref": "#/components/parameters/LeaderboardId"
          },
          {
            "$ref": "#/components/parameters/PlayerId"
          }
        ],
        "responses": {
          "201": {
            "description": "Player is enrolled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnrollmentStatus"
                },
                "example": {
                  "leaderboardId": "lb-11111111-1111-1111-1111-111111111111",
                  "playerId": "player-123",
                  "isEnrolled": true,
                  "enrolledAt": "2025-05-11T10:00:00.000Z",
                  "costCurrencyId": "c3d4e5f6-a7b8-9012-cdef-012345678912",
                  "costAmount": 50
                }
              }
            }
          },
          "400": {
            "description": "The target leaderboard is not a tournament, or the player cannot enroll.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "statusCode": 400,
                  "message": "Only tournaments require enrollment",
                  "error": "Bad Request"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "BrandId": {
        "name": "brandId",
        "in": "path",
        "required": true,
        "description": "Brand UUID returned by `GET /brands/default/{tenantId}`.",
        "schema": {
          "type": "string",
          "format": "uuid",
          "example": "aebb6a6a-bdef-480f-8096-e13f9c3d4969"
        }
      },
      "PlayerId": {
        "name": "playerId",
        "in": "path",
        "required": true,
        "description": "Your internal player/customer identifier.",
        "schema": {
          "type": "string",
          "example": "player-123"
        }
      },
      "LeaderboardId": {
        "name": "leaderboardId",
        "in": "path",
        "required": true,
        "description": "Leaderboard UUID (from the leaderboards list `id`).",
        "schema": {
          "type": "string",
          "example": "lb-11111111-1111-1111-1111-111111111111"
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "Resource not found (brand, player, mission, leaderboard, etc.).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "statusCode": 404,
              "message": "Not found",
              "error": "Not Found"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Standard NestJS error response.",
        "properties": {
          "statusCode": {
            "type": "integer",
            "example": 404
          },
          "message": {
            "type": "string",
            "example": "Not found"
          },
          "error": {
            "type": "string",
            "example": "Not Found"
          }
        }
      },
      "EnrollmentStatus": {
        "type": "object",
        "properties": {
          "leaderboardId": {
            "type": "string"
          },
          "playerId": {
            "type": "string"
          },
          "isEnrolled": {
            "type": "boolean"
          },
          "enrolledAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "costCurrencyId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "costAmount": {
            "type": "integer",
            "nullable": true
          }
        }
      }
    }
  }
}
```