Features

Free spins

Free spins are spins you give a player at a fixed bet. They are played in the game's own client and cost the player nothing. Use the methods below to grant them from your back office or CRM.

• Available for games with free_spins: true in /games/health (1009 of 1010 games).
• All methods are POST https://notell-api.com/gameActions.do with a method field. They need partner, api_key and an allowlisted IP.
• The optional Idempotency-Key header is supported by every method on this page (Conventions). Common errors (UNAUTHORIZED, IP_NOT_ALLOWED, INVALID_IDEMPOTENCY_KEY, IDEMPOTENCY_CONFLICT, RATE_LIMITED) are listed in Errors and not repeated in the tables below.
• The legacy methods freespins_set, freespins_delete and freespins_get without an id answer METHOD_RETIRED.
• Free spins are not available in demo mode.

How free spins work#

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). A grant applies only to the same player_id and the same currency it was created for.
• 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 (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 grant is finished only after 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).
• bet and the project bet limits are checked when the grant is created, and again when a spin is played.

Wallet callbacks of a grant#

Every free-spin round sends a bet with amount 0 and meta.is_freespins: true. Your wallet must accept the zero bet (Wallet callbacks).

The wins of a grant are held and paid once. Winning rounds are not sent to your wallet one by one. When the last round of the grant has settled, the platform sends one win for the whole amount and only then the freespins_finished summary. The win is sent only if the total is above zero. Its transaction is stable across retries, and it is repeated until you answer ok.

{
  "method": "win",
  "player_id": "player-1024",
  "amount": 23.5,
  "meta": {
    "symbol": "gates-of-olympus",
    "time": 1803295800,
    "transaction": "e8a2b6c4-1d3f-4a57-9b0e-6c7d2f1a3e55",
    "round_id": "b2a74c1e-5d90-4f3a-8c21-0e9b7a6d4f12",
    "session_id": "9d0c3f7e-2b1a-4c58-a6d3-7e4f1b0c9a28",
    "is_freespins": true,
    "freespins": {
      "grant_id": "7b1c0e52-4f6a-4d8e-9a31-2c5e8f90b1d4",
      "external_id": "spring-promo-1",
      "nominal_bet": 1,
      "total_win": 23.5,
      "final_credit": true
    }
  },
  "api_key": "YOUR_API_KEY"
}

meta.round_id is the last settled round of the grant. The player's balance in the game is updated locally while the spins are played; your wallet is credited by this one win. Then the summary is sent.

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). A grant with unsettled rounds waits for them first.

{
  "method": "freespins_finished",
  "grant_id": "7b1c0e52-4f6a-4d8e-9a31-2c5e8f90b1d4",
  "external_id": "spring-promo-1",
  "player_id": "player-1024",
  "currency": "EUR",
  "game": "gates-of-olympus",
  "status": "used",
  "total": 10,
  "played": 10,
  "bet": "1.00",
  "total_win": "23.50",
  "finished_at": "2027-02-15T12:30:00.000Z",
  "api_key": "YOUR_API_KEY"
}

Use it to close the promotion on your side. The money has already been credited by the final win above.

freespins_create#

Creates a grant for one player in one game.

Request#

curl -s -X POST https://notell-api.com/gameActions.do \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: spring-promo-1-player-1024' \
  -d '{
    "method": "freespins_create",
    "partner": "demo-casino",
    "api_key": "YOUR_API_KEY",
    "player_id": "player-1024",
    "currency": "EUR",
    "symbol": "gates-of-olympus",
    "count": 10,
    "bet": "1.00",
    "external_id": "spring-promo-1",
    "meta": {"campaign": "spring"}
  }'

{
  "method": "freespins_create",
  "partner": "demo-casino",
  "api_key": "YOUR_API_KEY",
  "player_id": "player-1024",
  "currency": "EUR",
  "symbol": "gates-of-olympus",
  "count": 10,
  "bet": "1.00",
  "external_id": "spring-promo-1",
  "meta": {"campaign": "spring"}
}

Response#

{
  "status": "ok",
  "grant": {
    "grant_id": "7b1c0e52-4f6a-4d8e-9a31-2c5e8f90b1d4",
    "external_id": "spring-promo-1",
    "player_id": "player-1024",
    "currency": "EUR",
    "symbol": "gates-of-olympus",
    "provider": "pragmatic",
    "total": 10,
    "remaining": 10,
    "played": 0,
    "bet": "1.00",
    "total_win": "0.00",
    "status": "active",
    "created_at": "2027-02-15T10:00:00.000Z",
    "expires_at": "2027-02-28T12:00:00.000Z",
    "finished_at": null
  }
}

Errors#

freespins_get#

Returns one grant by grant_id or by your external_id.

Request#

curl -s -X POST https://notell-api.com/gameActions.do \
  -H 'Content-Type: application/json' \
  -d '{"method":"freespins_get","partner":"demo-casino","api_key":"YOUR_API_KEY","external_id":"spring-promo-1"}'

{
  "method": "freespins_get",
  "partner": "demo-casino",
  "api_key": "YOUR_API_KEY",
  "external_id": "spring-promo-1"
}

Response#

The same {"status": "ok", "grant": {…}} as in freespins_create, with current remaining, played, total_win and status.

{
  "status": "ok",
  "grant": {
    "grant_id": "7b1c0e52-4f6a-4d8e-9a31-2c5e8f90b1d4",
    "external_id": "spring-promo-1",
    "player_id": "player-1024",
    "currency": "EUR",
    "symbol": "gates-of-olympus",
    "provider": "pragmatic",
    "total": 10,
    "remaining": 6,
    "played": 4,
    "bet": "1.00",
    "total_win": "7.20",
    "status": "active",
    "created_at": "2027-02-15T10:00:00.000Z",
    "expires_at": "2027-02-28T12:00:00.000Z",
    "finished_at": null
  }
}

Errors#

freespins_list#

Lists grants of your project, newest first, at most 200.

Request#

curl -s -X POST https://notell-api.com/gameActions.do \
  -H 'Content-Type: application/json' \
  -d '{"method":"freespins_list","partner":"demo-casino","api_key":"YOUR_API_KEY","player_id":"player-1024","status":"active"}'

{
  "method": "freespins_list",
  "partner": "demo-casino",
  "api_key": "YOUR_API_KEY",
  "player_id": "player-1024",
  "status": "active"
}

Response#

{
  "status": "ok",
  "grants": [
    {
      "grant_id": "7b1c0e52-4f6a-4d8e-9a31-2c5e8f90b1d4",
      "external_id": "spring-promo-1",
      "player_id": "player-1024",
      "currency": "EUR",
      "symbol": "gates-of-olympus",
      "provider": "pragmatic",
      "total": 10,
      "remaining": 6,
      "played": 4,
      "bet": "1.00",
      "total_win": "7.20",
      "status": "active",
      "created_at": "2027-02-15T10:00:00.000Z",
      "expires_at": "2027-02-28T12:00:00.000Z",
      "finished_at": null
    }
  ]
}

Errors#

freespins_cancel#

Cancels an active grant: the unused spins are dropped. Repeating the call returns the same grant. A grant that is not active or has no spins left is returned unchanged.

Request#

curl -s -X POST https://notell-api.com/gameActions.do \
  -H 'Content-Type: application/json' \
  -d '{"method":"freespins_cancel","partner":"demo-casino","api_key":"YOUR_API_KEY","grant_id":"7b1c0e52-4f6a-4d8e-9a31-2c5e8f90b1d4"}'

{
  "method": "freespins_cancel",
  "partner": "demo-casino",
  "api_key": "YOUR_API_KEY",
  "grant_id": "7b1c0e52-4f6a-4d8e-9a31-2c5e8f90b1d4"
}

Response#

{
  "status": "ok",
  "grant": {
    "grant_id": "7b1c0e52-4f6a-4d8e-9a31-2c5e8f90b1d4",
    "external_id": "spring-promo-1",
    "player_id": "player-1024",
    "currency": "EUR",
    "symbol": "gates-of-olympus",
    "provider": "pragmatic",
    "total": 10,
    "remaining": 6,
    "played": 4,
    "bet": "1.00",
    "total_win": "7.20",
    "status": "cancelled",
    "created_at": "2027-02-15T10:00:00.000Z",
    "expires_at": "2027-02-28T12:00:00.000Z",
    "finished_at": "2027-02-17T09:15:00.000Z"
  }
}

finished_at is set, and the summary is queued, as soon as no round of the grant is unsettled: at once, or after a round that was in progress has settled (until then it is null).

Errors#

See also#

• Wallet callbacks: the zero bet, the final win and freespins_finished.
• Bet limits and Currencies.
• Admin: the same grants can be managed in the admin panel.