Features

Free spins

Operator free spins are spins you give a player at a fixed bet. They are played in the game's own client (as free rounds, bonus spins or free bets, depending on the provider) and cost the player nothing.

• Available for games with free_spins: true in /games/health (445 of 446 games).
• Methods are POST /gameActions.do with method set; the call needs partner, api_key and an allowlisted IP.
• The admin panel offers the same functions on the Free spins screen (Admin: operations).

Methods#

An optional Idempotency-Key header is supported (Conventions). The legacy methods freespins_set and freespins_delete, and freespins_get without an id, answer METHOD_RETIRED.

Create a grant#

curl -s -X POST https://notell-api.com/gameActions.do \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: promo-2026-10-player-123' \
  -d '{
    "method": "freespins_create",
    "partner": "YOUR_PARTNER_ID",
    "api_key": "YOUR_API_KEY",
    "player_id": "player-123",
    "currency": "UAH",
    "symbol": "gates-of-olympus",
    "count": 10,
    "bet": "1.00",
    "expires_at": "2026-11-01T12:00:00Z",
    "external_id": "promo-2026-10",
    "meta": {"campaign": "autumn"}
  }'

{
  "status": "ok",
  "grant": {
    "grant_id": "7b1c0e52-…",
    "external_id": "promo-2026-10",
    "player_id": "player-123",
    "currency": "UAH",
    "symbol": "gates-of-olympus",
    "provider": "pragmatic",
    "total": 10,
    "remaining": 10,
    "played": 0,
    "bet": "1.00",
    "total_win": "0.00",
    "status": "active",
    "created_at": "2026-10-15T10:00:00.000Z",
    "expires_at": "2026-11-01T12:00:00.000Z",
    "finished_at": null
  }
}

The admin panel's grant form lists the valid bets of the chosen game and, when the project maximum is above the game's native maximum, the extended bets up to it.

The grant object#

Lifecycle and statuses#

active --last spin settled--> used
active --expires_at passed--> expired     (unused spins are dropped)
active --freespins_cancel---> cancelled

• A player can hold several grants per game. The grant that expires first is played first (ties: the older one first).
• While a grant is active the player can play only the free spins in that game: paid spins, ante bets and bonus buys are refused by the game (FREE_SPINS_ACTIVE) until the grant is used up, expires or is cancelled.
• A round that already started when its grant expires or is cancelled finishes and is credited normally; the summary callback waits for it.
• Free-spin rounds go through the same RTP logic as paid rounds and count in the player's adaptive RTP window with their nominal bet (RTP management).

Wallet interplay#

Every free-spin round sends a bet with amount 0 and meta.is_freespins: true to your wallet; a winning round sends win with the same meta. Your wallet must accept the zero bet. Details: Wallet callbacks.

Summary callback#

When a grant finishes (used, expired or cancelled) the platform sends exactly one freespins_finished callback to your wallet URL and repeats it until you answer ok (delays of 10 s × 2^attempts, at most 1 hour):

{
  "method": "freespins_finished",
  "grant_id": "7b1c0e52-…",
  "external_id": "promo-2026-10",
  "player_id": "player-123",
  "currency": "UAH",
  "game": "gates-of-olympus",
  "status": "used",
  "total": 10,
  "played": 10,
  "bet": "1.00",
  "total_win": "23.50",
  "finished_at": "2026-10-15T12:30:00.000Z",
  "api_key": "YOUR_API_KEY"
}

Use it to close the promotion on your side and to report the total win. The win itself has already been credited through the usual win operations.

Other methods#

# one grant by your external id
curl -s -X POST https://notell-api.com/gameActions.do -H 'Content-Type: application/json' \
  -d '{"method":"freespins_get","partner":"YOUR_PARTNER_ID","api_key":"YOUR_API_KEY","external_id":"promo-2026-10"}'

# list active grants of a player
curl -s -X POST https://notell-api.com/gameActions.do -H 'Content-Type: application/json' \
  -d '{"method":"freespins_list","partner":"YOUR_PARTNER_ID","api_key":"YOUR_API_KEY","player_id":"player-123","status":"active"}'

# cancel (repeating returns the same grant)
curl -s -X POST https://notell-api.com/gameActions.do -H 'Content-Type: application/json' \
  -d '{"method":"freespins_cancel","partner":"YOUR_PARTNER_ID","api_key":"YOUR_API_KEY","grant_id":"7b1c0e52-…"}'

freespins_get and freespins_cancel need exactly one of grant_id and external_id.

Errors#

UNAUTHORIZED, IP_NOT_ALLOWED, INVALID_REQUEST, GAME_NOT_FOUND, FREE_SPINS_UNSUPPORTED, INVALID_COUNT, INVALID_FREE_SPIN_BET, PROJECT_BET_LIMIT, INVALID_EXPIRY, DUPLICATE_EXTERNAL_ID, GRANT_NOT_FOUND, METHOD_RETIRED, IDEMPOTENCY_CONFLICT — see the error reference.