Welcome to the Loyalty System

This is the API Reference for the Optimove Loyalty System API. Each page in the sidebar documents a single endpoint with its parameters, request/response schemas, and a "Try It" panel for live calls.

📘
Building a widget?
If you are integrating the Loyalty System for the first time, start with the Custom widget UI integration guide. It walks through the typical page-load sequence, data model, and player-action flows before you dive into individual endpoints.

Environments

Environment	Base URL
Production US	`https://opti-ls-api-us.optimove.net/api`
Production EU	`https://opti-ls-api-eu.optimove.net/api`

Choose the base URL that matches your tenant's region.

Authentication

📘
Auth is not yet enforced
Authentication is not currently 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.

CORS

⚠️
Allow-listed origins
Requests from certain origins are permitted by default. If your widget runs on a domain outside that set, raise a request with the Optimove team to have it added before starting development.

Error responses

All error responses follow the standard NestJS shape:

{ "statusCode": 404, "message": "Resource not found", "error": "Not Found" }

Status	Meaning
`400`	Invalid request body or parameters
`404`	Resource not found (brand, player, mission, etc.)
`409`	Conflict (for example, display name already taken)
`500`	Internal server error

OpenAPI spec

The complete OpenAPI 3.0 spec is available for download from the top of this page. Import it into Postman, Insomnia, or any OpenAPI-compatible tool for an offline reference.

Where to next

First-time integration: read the Custom widget UI integration guide.
Resolving brandId: start with getDefaultBrand.
Player widget data: getWidgetTheme, getPlayerProfile, getPlayerLevel, getPlayerMissions, getPlayerCalculatedRewards, getRewardsCatalog, getPlayerRewards, getPlayerBadges, listLeaderboards.
Player actions: updatePlayerName, unlockMission, claimMissionReward, claimLevelReward, enrollInTournament.
Leaderboard data: getPlayerLeaderboardEnrollment, getPlayerLeaderboardRank, getLeaderboardTop, getLeaderboardRankRange.