Free Round Bonuses

Free Round Bonuses

Info

Free Round Bonuses (FRBs) are promotional tools that allow casino operators to offer free spins to players. This section covers the complete lifecycle of Free Round Bonuses within the Groove platform.

Overview

Free Round Bonuses are a powerful marketing tool that allow casinos to:

  • Attract new players with risk-free gameplay offers
  • Re-engage existing players with promotional incentives
  • Reward loyal players with bonus gameplay
  • Promote specific games or game providers

The Groove API provides a comprehensive set of endpoints to manage the entire Free Round Bonus lifecycle, from template creation to player redemption and reporting.

FRB Lifecycle

graph TD A[Create FRB Template] -->|Define bonus parameters| B[Configure Template] B -->|Set game, wager, max win| C[Ready for Assignment] C -->|Assign to players| D[Grant FRB to Players] D -->|Bonus activation| E[Player Uses Bonus] E -->|Track usage| F[Monitor Status] F -->|Optional| G[Cancel Unused FRB] H[Create and Grant FRB] -->|Single operation: Create + Grant| E style A fill:#e6f7ff,stroke:#333,stroke-width:2px style B fill:#f0f0f0,stroke:#333,stroke-width:1px style C fill:#f0f0f0,stroke:#333,stroke-width:1px style D fill:#e6f7ff,stroke:#333,stroke-width:2px style E fill:#f0f0f0,stroke:#333,stroke-width:1px style F fill:#e6f7ff,stroke:#333,stroke-width:2px style G fill:#ffe6e6,stroke:#333,stroke-width:1px style H fill:#d4f1d4,stroke:#333,stroke-width:2px

Free Round Bonus Process Flow

The following sequence diagram illustrates how Free Round Bonuses are processed through the Groove platform:

sequenceDiagram participant Casino as Casino Operator participant Groove as Groove Platform participant Game as Game Provider participant Player Casino->>Groove: Create FRB Template Groove->>Casino: Template ID Response Casino->>Groove: Grant FRB to Player Groove->>Casino: FRB Assignment Confirmation Player->>Casino: Login & Launch Game Groove->>Game: Initialize Game with FRB Parameters Game->>Player: Display Game with Free Spins Available rect rgb(240, 240, 240) Note over Player,Casino: Free Spin Usage Player->>Game: Use Free Spin Game->>Groove: Wager Request (amount=0) Groove->>Casino: Forward Wager Request Casino->>Groove: Wager Response Groove->>Game: Forward Response Game->>Player: Display Spin Outcome Game->>Groove: Result Request (win amount) Groove->>Casino: Forward Result Request Casino->>Groove: Result Response Groove->>Game: Forward Response Game->>Player: Display Win & Updated Balance end Casino->>Groove: Get FRB Status Request Groove->>Casino: FRB Status Response alt Unused FRB Expiration Casino->>Groove: Cancel FRB Request Groove->>Casino: Cancel FRB Confirmation end

Key FRB Components

FRB Template

A template defines the parameters of a Free Round Bonus offer, including:

  • Eligible games
  • Number of free spins
  • Bet amount for each spin
  • Maximum win amount
  • Validity period

FRB Grant

The process of assigning a template-based bonus to a specific player or group of players.

FRB Status

Tracking mechanism for monitoring the usage and status of bonuses granted to players.

FRB Cancellation

Method for revoking unused bonuses when needed (e.g., expired offers).

Available FRB Operations

The Groove API provides the following endpoints for managing Free Round Bonuses:

Operation Description Endpoint
Create FRB Template Define bonus parameters /frb/create/{version}/template
Grant FRB to Players Assign bonus to players /frb/grant/{version}/players
Create and Grant FRB Create template and grant in single operation /frb/create/{version}/template-and-grant
Get FRB Status Check bonus usage status /frb/{version}/bonus?operator_id=XXXXX&template_id=XXXXX&player_id=XXXXX
FRB Metadata Retrieve bonus information /frb/games/{version}/metadata
Cancel FRB Revoke unused bonuses /frb/{version}/bonus?operator_id=XXXXX&template_id=XXXXX&player_id=XXXXX

Free Chips (Live Dealer Free Round Bonuses)

Info

Some game providers support **Free Chips**, which is the live dealer equivalent of Free Spins. Free Chips allow casino operators to offer free rounds on live dealer games (e.g., Blackjack, Roulette) using the same FRB API endpoints.

Free Chips work through the same API flow as standard Free Round Bonuses — the same endpoints are used for template creation, granting, status checks, and cancellation. The platform automatically routes the request to the correct flow (Free Spins or Free Chips) based on the game category.

Limitations

Warning

**Mixed game types are not supported.** A template must contain either all slot games or all live dealer games. Templates with a mix of slot and live dealer games will be rejected.

  • The chip value is determined by the provider’s available chip values. Operators must ensure the selected bet value is appropriate for live dealer games, where minimum bets are typically higher than slots.
  • Free Chips availability depends on provider support. Not all game providers support Free Chips for live dealer games.
  • The same template cannot contain both slot and live dealer games. If a mixed game list is submitted, the request will fail.

Implementation Guidelines

When implementing Free Round Bonuses, follow these best practices:

  1. Template Management

    • Create templates with clear identification and purpose
    • Set appropriate limits on maximum wins
    • Define reasonable validity periods

  2. Player Assignment

    • Target specific player segments for maximum effectiveness
    • Provide clear terms and conditions
    • Implement proper validation before granting

  3. Monitoring and Reporting

    • Regularly check bonus usage status
    • Analyze performance of different bonus offers
    • Maintain audit trails for all bonus activities

  4. Error Handling

    • Implement comprehensive error handling for all FRB operations
    • Handle edge cases like attempting to use expired bonuses
Warning

Free Round Bonuses must comply with relevant gambling regulations in your jurisdiction. Ensure your implementation meets all regulatory requirements regarding bonus offers and promotions.

Next Steps

Explore the specific FRB operations in the following sections to implement a complete Free Round Bonus system for your casino.

Subsections of Free Round Bonuses

Retrieve game provider FRB metadata

Retrieve game provider FRB metadata

Retrieves FRB metadata from the game providers, grouped by provider name. Each provider entry includes the template fields the operator must supply when creating a template, along with the list of eligible games.

Request Method: GET

Option 1: All providers

Returns metadata for all providers that support FRB.

Request endpoint: /frb/games/{version}/metadata?subProvider=1

Request parameters:

Parameter Data type Description
version String required The API version. Only version 1.0 is currently supported. Other version values are accepted, but are treated as 1.0.
Example: v1
subProvider Integer required Must be 1. Activates provider-level grouping by provider name.

This option does not require an authorization header.

Option 2: Filtered by operator

Returns metadata for only the providers enabled for a specific operator (casino).

Request endpoint: /frb/games/{version}/metadata?subProvider=1&operator_id={casinoId}

Request parameters:

Parameter Data type Description
version String required The API version. Only version 1.0 is currently supported. Other version values are accepted, but are treated as 1.0.
Example: v1
subProvider Integer required Must be 1. Activates provider-level grouping by provider name.
operator_id Integer required Groove operator ID (casino ID). Only providers enabled for this operator are returned.

Authorization:

Header Required Description
jwt-auth Yes Sinatra back office session token obtained from login.
Warning

operator_id must be numeric. Sending a non-numeric value returns HTTP 400.

Example Response (both options):

{
  "BetSoft": {
    "providerId": 82,
    "fieldsToDefine": {
      "numberOfRounds": {
        "type": "Integer",
        "maxValue": 2147483647,
        "minValue": 0
      },
      "availableFromDate": {
        "type": "Date",
        "format": "yyyy-MM-dd HH:mm:ss"
      },
      "availableDuration": {
        "type": "Integer"
      },
      "expirationDate": {
        "type": "Date",
        "format": "yyyy-MM-dd HH:mm:ss"
      },
      "messageFirstLine": {
        "type": "String",
        "isOptional": false
      },
      "messageSecondLine": {
        "type": "String",
        "isOptional": false
      },
      "offerName": {
        "type": "String",
        "isOptional": false
      }
    },
    "gameInfoList": [
      {
        "gameId": "82600118",
        "betAmount": [0]
      },
      {
        "gameId": "82600200",
        "betAmount": [0]
      }
    ]
  },
  "Wazdan": {
    "providerId": 95,
    "fieldsToDefine": {
      "numberOfRounds": {
        "type": "Integer",
        "maxValue": 2147483647,
        "minValue": 0
      },
      "availableFromDate": {
        "type": "Date",
        "format": "yyyy-MM-dd HH:mm:ss"
      },
      "availableDuration": {
        "type": "Integer"
      },
      "expirationDate": {
        "type": "Date",
        "format": "yyyy-MM-dd HH:mm:ss"
      },
      "offerName": {
        "type": "String",
        "isOptional": false
      }
    },
    "gameInfoList": [
      {
        "gameId": "95000012",
        "betAmount": [0]
      }
    ]
  }
}
Info

The response is a map keyed by provider name. Each entry contains:

  • providerId — the numeric ID of the provider
  • fieldsToDefine — the template fields required by that provider (varies per provider)
  • gameInfoList — the games eligible for FRB under that provider, each with a gameId and betAmount array

When using Option 2, only providers enabled for the specified operator are included in the response.

Error Response:

{
  "error": "operator_id must be numeric"
}

Response codes:

Code Status Message
200 success 200 success Got games providers FRB metadata successfully
400 bad request operator_id must be numeric / authorization header missing
403 forbidden operator is not in the user’s available operators list
500 internal server error internal server error

Create FRB template

Create FRB template

Creates one or more FRB templates for the specified provider(s).

Request endpoint: /frb/create/{version}/template?subProvider=1

Request Method: POST

Usage information

The request body is a JSON array. Each element defines a template for a single provider.

Note

This request requires an authorization token: Bearer authorization token.
Token Format: The authorization token must be Base64-encoded as follows:
AuthorizationToken = encode(back_office_email:back_office_password)

Note
  • The specified parameters operatorId and providerName must already be configured in Groove.
  • For Playson, the template must contain only one game.
  • For Pragmatic Play, the expiration date of the template must be no more than 30 days from the template start date.
Warning

Mixed game types are not supported. All games in a template must be of the same type — either all slot games or all live dealer games. Templates containing a mix of slot and live dealer games will be rejected. This applies to providers that support both Free Spins (slots) and Free Chips (live dealer).

Info

For QuickFire, parameter balanceTypeId is required. This parameter is not used by any other game provider. Valid values are:

  • 0: Real money
  • 1: Bonus money
Info

How the bet amount works

  • The player’s bet per spin is betAmount × betValue. betValue is the value for the player’s currency.
  • betValue is a fixed value per currency, not a live exchange rate. For example, EUR and USD both have 0.01, so betAmount: 100 gives 1.00 EUR and also 1.00 USD.
  • Examples with betAmount: 100:
    • EUR player (betValue 0.01): 1.00 EUR per spin
    • BRL player (betValue 0.05): 5.00 BRL per spin
    • JPY player (betValue 1): 100 JPY per spin
  • The full list of currencies and values is available from Get FRB currency values.
  • The betAmount you send is used only when a non-default bet amount is enabled for your casino. To enable it, contact your account manager.
  • Otherwise, or when useDefaultAmount is true or betAmount is 0, the game provider’s default bet amount is used.
  • A game may not support the exact amount. In that case, the closest bet amount the game supports is used.

Request parameters:

Parameter Data type Description
version String required The API version. Only version 1.0 is currently supported. Other version values are accepted, but are treated as 1.0.
Example: v1
subProvider Integer required Must be 1. Ensures the provider name you send is resolved correctly and the response contains the correct providerId.
Authorization Yes (Header) Sinatra back office user

Request Body

[
  {
    "providerName": "BetSoft",
    "operatorId": 11,
    "numberOfRounds": 10,
    "availableFromDate": "2026-04-29 00:00:00",
    "availableDuration": 7,
    "expirationDate": "2026-05-06 00:00:00",
    "messageFirstLine": "Enjoy your free spins!",
    "messageSecondLine": "Play now",
    "offerName": "WelcomeBonus",
    "gameInfoList": [
      {
        "gameId": "82600118",
        "betAmount": [100]
      }
    ]
  }
]
Note

betAmount is multiplied by the betValue of the player’s currency. See “How the bet amount works” above.

The response body includes the id parameter in the root object. This is the template collection ID used when granting the FRB to players.

Response Parameters:

None.

Example Response:

Success response:

{
  "id": "663b1f77bcf86cd799439011",
  "done": true,
  "offer_names": ["WelcomeBonus"],
  "succeeded_providers": ["BetSoft"],
  "failed_providers": [],
  "succeeded_insertion": [
    {
      "id": "663b1f77bcf86cd799439012",
      "templateId": "TMP_82600118_11_BetSoft",
      "providerName": "BetSoft",
      "providerId": 82,
      "operatorId": 11,
      "transactionId": "",
      "numberOfRounds": 10,
      "availableFromDate": "2026-04-29 00:00:00",
      "availableDuration": 7,
      "expirationDate": "2026-05-06 00:00:00",
      "messageFirstLine": "Enjoy your free spins!",
      "messageSecondLine": "Play now",
      "offerName": "WelcomeBonus",
      "gameInfoList": [
        {
          "gameId": "82600118",
          "betAmount": [100]
        }
      ],
      "exceptionResponses": [],
      "players": []
    }
  ],
  "failed_insertion": []
}
Info
  • If the request is successful, the response will contain a list of successfully created templates (succeeded_insertion).
  • providerName and providerId in the response reflect the provider name you sent in the request and its numeric ID.
  • offerName is echoed back unchanged.
  • Upon granting the FRB template, the template ID that should be sent is the id field of the root object (e.g., "663b1f77bcf86cd799439011").

Error Response:

{
  "error": "Sub-provider does not exist or does not support FRB: UnknownProvider"
}

Response codes:

Code Status Message
200 success Template(s) created successfully
400 bad request bad request
422 Invalid parameters One of:
• bet amount should be an integer
• no metadata fields for this provider
• Available date is empty
• Available date should be with format yyyy-MM-dd HH:mm:ss
• Available date should be a future date
• Expiration date is empty
• Expiration date should be with format yyyy-MM-dd HH:mm:ss
• Expiration date should be a future date
• Number of rounds is empty
• Balance type id is empty
• Balance type id allowed values are 0 or 1
• Wrong balance type id size - values are 0 or 1
• Offer name can not be more than 255 characters
• Game info list is empty
• Game id not exist in this provider
• provider supports only single game
• Sub-provider does not exist or does not support FRB
500 internal server error internal server error

Grant FRB to players

Grant FRB to players

Grant a free round bonus to one or more players using a previously created template.

Request endpoint: /frb/grant/{version}/players?subProvider=1

Request Method: POST

Usage information:

The request body specifies the template to grant and the target players.

Note

This request requires an authorization token: Bearer authorization token.
Token Format: The authorization token must be Base64-encoded as follows:
AuthorizationToken = encode(back_office_email:back_office_password)

Note

For Playson and Evoplay Entertainment, only one player can be sent in the array.

Note

templateId should be the id field from the root object returned by the Create FRB template endpoint.

The bet per spin comes from the template’s betAmount.

Info

How the bet amount works

  • The player’s bet per spin is betAmount × betValue. betValue is the value for the player’s currency.
  • betValue is a fixed value per currency, not a live exchange rate. For example, EUR and USD both have 0.01, so betAmount: 100 gives 1.00 EUR and also 1.00 USD.
  • Examples with betAmount: 100:
    • EUR player (betValue 0.01): 1.00 EUR per spin
    • BRL player (betValue 0.05): 5.00 BRL per spin
    • JPY player (betValue 1): 100 JPY per spin
  • The full list of currencies and values is available from Get FRB currency values.
  • The betAmount you send is used only when a non-default bet amount is enabled for your casino. To enable it, contact your account manager.
  • Otherwise, or when useDefaultAmount is true or betAmount is 0, the game provider’s default bet amount is used.
  • A game may not support the exact amount. In that case, the closest bet amount the game supports is used.

In the response body, templateId inside succeeded_frb_awarded is the granted template ID. Use this ID for subsequent status checks and cancellations.

Request parameters:

Parameter Data type Description
version String required The API version. Only version 1.0 is currently supported. Other version values are accepted, but are treated as 1.0.
Example: v1
subProvider Integer required Must be 1. Ensures the response contains the correct providerName and providerId.
Authorization Yes (Header) Sinatra back office user

Request body:

{
  "templateId": "663b1f77bcf86cd799439011",
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "players": [
    {
      "playerId": "player_001",
      "playerCurrency": "EUR",
      "playerCountry": "USA"
    }
  ]
}
Note
  • transactionId - (optional) The unique transaction ID for this request, generated by the casino platform. This is used for idempotency, to avoid processing the same request multiple times. If a request with the same transactionId has already been processed, the system will return the result of the previous request instead of processing it again, we recommend sending it in UUID format, while there is no validation on groove side, some providers have, and our internal tests use UUID.V4
  • Currency - ISO 4217 currency code, should be the same as the currency of the player, which is used to play the game.
  • Country - alpha-3 country code, should be the same as the country (alpha-2) of the player, which is used to play the game.

Response parameters:

None

Example Response

Success response

{
  "id": "663b1f77bcf86cd799439022",
  "templateId": "663b1f77bcf86cd799439011",
  "players": [
    {
      "playerId": "player_001",
      "playerCurrency": "EUR",
      "playerCountry": "USA"
    }
  ],
  "status": "Success",
  "templatesAwardedCollections": {
    "failed_frb_awarded": [],
    "succeeded_frb_awarded": [
      {
        "templateId": "TMP_82600118_11_BetSoft",
        "providerName": "BetSoft",
        "providerId": 82,
        "operatorId": 11,
        "numberOfRounds": 10,
        "availableFromDate": "2026-04-29 00:00:00",
        "availableDuration": 7,
        "expirationDate": "2026-05-06 00:00:00",
        "offerName": "WelcomeBonus",
        "gameInfoList": [
          {
            "gameId": "82600118",
            "betAmount": [100]
          }
        ],
        "players": [
          {
            "playerId": "player_001",
            "playerCurrency": "EUR",
            "playerCountry": "USA"
          }
        ],
        "status": "Success"
      }
    ]
  }
}
Info

For transactions(wager/result), the frbid which will be sent in request is the template id within succeeded_frb_awarded.

Info

For Get / Cancel FRB requests, the id which should be sent is the template id within succeeded_frb_awarded.

Error Response:

{
  "errMsg": "bad request"
}

Response codes:

Code Status Message
200 success FRB granted successfully
400 bad request bad request
422 Invalid parameters One of:
• bet amount should be an integer
• no metadata fields for this provider
• Available date is empty
• Available date should be with format yyyy-MM-dd HH:mm:ss
• Available date should be a future date
• Expiration date is empty
• Expiration date should be with format yyyy-MM-dd HH:mm:ss
• Expiration date should be a future date
• Number of rounds is empty
• Balance type id is empty
• Balance type id allowed values are 0 or 1
• Wrong balance type id size - values are 0 or 1
• Offer name can not be more than 255 characters
• Game info list is empty
• Game id not exist in this provider
• provider supports only single game
500 internal server error internal server error

Get FRB Status

Get FRB Status

Get the free round bonus information granted to a player.

Request endpoint: /frb/{version}/bonus?subProvider=1&operator_id=XXXXX&template_id=XXXXX&player_id=XXXXX

Request Method: GET

Usage information:

The request query parameters include the operator ID, template ID, and player ID.

Note

This request requires an authorization token: Bearer authorization token.
Token Format: The authorization token must be Base64-encoded as follows:
AuthorizationToken = encode(back_office_email:back_office_password)

Request parameters:

Parameter Data type Description
version String required The API version. Only version 1.0 is currently supported. Other version values are accepted, but are treated as 1.0.
Example: v1
subProvider Integer required Must be 1. Ensures the response provider_id reflects the correct provider.
operator_id Integer required Groove operator ID
template_id String required FRB grant template ID (the templateId from succeeded_frb_awarded in the grant response).
player_id String required The granted player ID.
Authorization Yes (Header) Sinatra back office user

Example Response

Success response

{
  "player_id": "player_001",
  "player_currency": "EUR",
  "operator_id": 11,
  "provider_id": 82,
  "status": "active",
  "template_id": "TMP_82600118_11_BetSoft",
  "left_rounds": 8,
  "total_rounds": 10,
  "expiration_date": "2026-05-06T00:00:00Z",
  "games": [
    {
      "game_id": "82600118",
      "bet_amount": [100],
      "currency": "EUR"
    }
  ],
  "error_message": ""
}
Info

provider_id in the response is the numeric ID of the provider used when creating the template.

Error Response:

{
  "player_id": "player_001",
  "player_currency": "EUR",
  "operator_id": 11,
  "provider_id": 82,
  "template_id": "TMP_82600118_11_BetSoft",
  "expiration_date": "2026-05-06T00:00:00Z",
  "error_message": "Internal Server Error"
}

Status Index:

Status Description
active The FRB is active, and the player can play.
canceled The FRB is inactive; the operator requested to cancel the bonus.
expired The FRB is inactive. The expiration date has passed.
completed The player has finished playing; no available rounds remain for this bonus.

Response codes:

Code Status Message
200 success 200 success Got FRB status successfully
400 bad request bad request
403 forbidden access forbidden access
500 internal server error internal server error

Cancel FRB

Cancel FRB

Cancel an active free round bonus granted to a player.

Request endpoint: /frb/{version}/bonus?subProvider=1&operator_id=XXXXX&template_id=XXXXX&player_id=XXXXX

Request Method: DELETE

Usage information:

The request query parameters include the operator ID, template ID, and player ID.

Note

This request requires an authorization token: Bearer authorization token.
Token Format: The authorization token must be Base64-encoded as follows:
AuthorizationToken = encode(back_office_email:back_office_password)

Request parameters:

Parameter Data type Description
version String required The API version. Only version 1.0 is currently supported. Other version values are accepted, but are treated as 1.0.
Example: v1
subProvider Integer required Must be 1. Ensures the response provider_id reflects the correct provider.
operator_id Integer required Groove operator ID
template_id String required FRB grant template ID (the templateId from succeeded_frb_awarded in the grant response).
player_id String required The granted player ID.
Authorization Yes (Header) Sinatra back office user

Example Response

Success response

{
  "player_id": "player_001",
  "player_currency": "EUR",
  "operator_id": 11,
  "provider_id": 82,
  "status": "canceled",
  "template_id": "TMP_82600118_11_BetSoft",
  "left_rounds": 8,
  "total_rounds": 10,
  "expiration_date": "2026-05-06T00:00:00Z",
  "games": [
    {
      "game_id": "82600118",
      "bet_amount": [100],
      "currency": "EUR"
    }
  ],
  "error_message": ""
}
Info

provider_id in the response is the numeric ID of the provider used when creating the template.

Error Response:

{
  "player_id": "player_001",
  "player_currency": "EUR",
  "operator_id": 11,
  "provider_id": 82,
  "template_id": "TMP_82600118_11_BetSoft",
  "expiration_date": "2026-05-06T00:00:00Z",
  "error_message": "Internal Server Error"
}

Status Index:

Status Description
active The FRB is active, and the player can play.
canceled The FRB is inactive; the operator requested to cancel the bonus.
expired The FRB is inactive. The expiration date has passed.
completed The player has finished playing; no available rounds remain for this bonus.

Http response codes:

Code Status Description
200 success 200 success status update
400 bad request bad request
403 forbidden access forbidden access
500 internal server error internal server error

Create and Grant FRB

Create and Grant FRB

Creates a new FRB template and immediately grants it to a player in a single atomic operation.

Request endpoint: /frb/create/{version}/template-and-grant?subProvider=1

Request Method: POST

Usage information

This unified endpoint combines template creation and player granting, eliminating the need for separate API calls and reducing the complexity of the FRB workflow. The template is created and immediately assigned to the specified player in a single transaction.

Note

This request requires an authorization token: Bearer authorization token.
Token Format: The authorization token must be Base64-encoded as follows:
AuthorizationToken = encode(back_office_email:back_office_password)

Warning

Single Entity Constraint: This endpoint supports:

  • One provider only — You can only specify a single game provider per request
  • One game only — You can only include one game in the games array
  • One player only — The bonus is granted to a single player specified in the request

For bulk operations or multiple games/players, use the separate Create FRB Template and Grant FRB to Players endpoints.

Note
  • The specified parameters operatorId and providerName must already be configured in Groove.
  • For Playson providers, the template must contain only one game (automatically enforced by this endpoint).
Info

How the bet amount works

  • The player’s bet per spin is betAmount × betValue. betValue is the value for the player’s currency.
  • betValue is a fixed value per currency, not a live exchange rate. For example, EUR and USD both have 0.01, so betAmount: 100 gives 1.00 EUR and also 1.00 USD.
  • Examples with betAmount: 100:
    • EUR player (betValue 0.01): 1.00 EUR per spin
    • BRL player (betValue 0.05): 5.00 BRL per spin
    • JPY player (betValue 1): 100 JPY per spin
  • The full list of currencies and values is available from Get FRB currency values.
  • The betAmount you send is used only when a non-default bet amount is enabled for your casino. To enable it, contact your account manager.
  • Otherwise, or when useDefaultAmount is true or betAmount is 0, the game provider’s default bet amount is used.
  • A game may not support the exact amount. In that case, the closest bet amount the game supports is used.

Request parameters:

Parameter Data type Description
version String required The API version. Only version 1.0 is currently supported. Other version values are accepted, but are treated as 1.0.
Example: v1
subProvider Integer required Must be 1. Ensures the provider name you send is resolved correctly and the response contains the correct providerId.
Authorization Yes (Header) Sinatra back office user

Request Body

{
  "providerName": "BetSoft",
  "operatorId": 11,
  "playerId": "player_001",
  "playerCurrency": "USD",
  "playerCountry": "US",
  "offerName": "WelcomeBonus",
  "numberOfRounds": 10,
  "availableDuration": 7,
  "useDefaultAmount": true,
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "games": [
    {
      "gameId": "82600118",
      "betAmount": [100]
    }
  ]
}

Request Body Fields

Field Type Required Description
providerName string Yes Name of the game provider (e.g., “Quickfire”, “EvoPlay”, “BetSoft”)
operatorId integer Yes Casino operator ID configured in Groove
playerId string Yes Player ID to whom the FRB template will be granted
playerCurrency string Yes Player’s currency code (ISO 4217 format, e.g., “USD”, “EUR”, “GBP”)
playerCountry string Yes Player’s country code (ISO 3166-1 alpha-2 format, e.g., “US”, “GB”, “DE”)
offerName string Yes Name/identifier for this bonus offer (max 255 characters)
numberOfRounds integer Yes Number of free rounds/spins to grant (must be greater than 0)
availableDuration integer Yes Duration in days the bonus will remain available from creation time
useDefaultAmount boolean No If true, the game provider’s default bet amount is used. If false or omitted, the bet amount in the games array is used when a non-default bet amount is enabled for your casino. Default: false
templateId string No Optional template ID for idempotency and tracking purposes. If not provided, one will be generated automatically
transactionId string No Optional unique transaction ID for idempotency. Used to prevent duplicate processing of the same request within a 120-second window. Auto-generated if not provided. We recommend UUID v4 format.
games array Yes Array containing exactly one game object (single game constraint)
games[].gameId string Yes Game identifier that must exist in the provider’s game catalog
games[].betAmount array Yes Array of bet amounts. Bet per spin = betAmount × betValue of the player’s currency (e.g., [100] gives 1.00 EUR or 5.00 BRL). Only the first value is used when a single game is specified
Note
  • availableDuration defines how many days from now the bonus will be valid. The system automatically calculates the start date (now) and expiration date (now + availableDuration days).
  • betAmount is multiplied by the betValue of the player’s currency (e.g., 100 = 1.00 EUR or 5.00 BRL). See “How the bet amount works” above.
  • Even though games is an array, only ONE game is allowed per request.

Response Parameters:

The response body includes comprehensive information about both the created template and the grant operation.

Example Response:

Success response:

{
  "id": "663b1f77bcf86cd799439033",
  "status": "Success",
  "template": {
    "templateId": "TMP_82600118_11_BetSoft",
    "providerName": "BetSoft",
    "providerId": 82,
    "operatorId": 11,
    "transactionId": "550e8400-e29b-41d4-a716-446655440000",
    "numberOfRounds": 10,
    "availableFromDate": "2026-04-29 00:00:00",
    "availableDuration": 7,
    "expirationDate": "2026-05-06 00:00:00",
    "offerName": "WelcomeBonus",
    "gameInfoList": [
      {
        "gameId": "82600118",
        "betAmount": [100]
      }
    ],
    "players": [
      {
        "playerId": "player_001",
        "playerCurrency": "USD",
        "playerCountry": "US"
      }
    ]
  },
  "grant": {
    "templateId": "TMP_82600118_11_BetSoft",
    "transactionId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "Success",
    "message": "Template awarded successfully",
    "playerId": "player_001",
    "playerCurrency": "USD",
    "playerCountry": "US",
    "exceptionResponses": []
  }
}

Response Body Fields

Field Type Description
id string Unique identifier of the response document
status string Overall operation status (“Success” or “Failed”)
template object Information about the created template
template.templateId string Generated template identifier used for tracking and future operations
template.providerName string Game provider name (same value sent in the request)
template.providerId integer Provider numeric ID
template.operatorId integer Casino operator ID
template.transactionId string Transaction ID (provided or auto-generated)
template.numberOfRounds integer Number of free rounds
template.availableFromDate string Datetime when the bonus becomes available (format: YYYY-MM-DD HH:mm:ss)
template.availableDuration integer Duration in days the bonus is valid
template.expirationDate string Datetime when the bonus expires (format: YYYY-MM-DD HH:mm:ss)
template.offerName string Bonus offer name (unchanged from request)
template.gameInfoList array List of games included in the template
template.gameInfoList[].gameId string Game identifier
template.gameInfoList[].betAmount array Bet amounts (multiplied by the betValue of the player’s currency)
template.players array List of players (contains single player)
grant object Information about the grant operation
grant.templateId string Template ID that was granted (use this ID for status checks and cancellations)
grant.transactionId string Transaction ID for this grant operation
grant.status string Grant operation status
grant.message string Descriptive message about the grant result
grant.playerId string Player ID who received the bonus
grant.playerCurrency string Player’s currency
grant.playerCountry string Player’s country
grant.exceptionResponses array List of any errors or warnings during the grant process (empty on success)
Info
  • The grant.templateId returned in the response should be used for subsequent operations:
  • If exceptionResponses contains entries, review them for warnings or partial failures.

Error Response:

{
  "error": "Sub-provider does not exist or does not support FRB"
}

Or for validation errors:

[
  "Game validation error: invalid game id",
  "Number of rounds must be greater than 0"
]

Response codes:

Code Status Message
200 success FRB template created and granted successfully
400 bad request Invalid JSON format or malformed request body
422 Invalid parameters One of:
• Offer name is empty
• Offer name can not be more than 255 characters
• Number of rounds must be greater than 0
• Available duration must be greater than 0
• Game info list is empty
• Only one game is allowed in create-and-grant endpoint
• Game id does not exist in provider’s catalog
• Bet amount should be an integer
• Player id is empty
• Player currency is empty
• Player country is empty
• Provider name is empty or invalid
• Operator id is empty or not configured
• Sub-provider does not exist or does not support FRB
500 internal server error Internal server error occurred during processing

Key Features

Atomic Operation

The template creation and player granting happen in a single transaction, ensuring data consistency. If either operation fails, the entire request is rolled back.

Idempotency

Duplicate requests are prevented using a combination of templateId and transactionId. If the same request is sent within a 120-second window, the cached response is returned instead of processing the request again.

Template Reuse

The system automatically checks if an identical template already exists (based on provider, operator, games, and offer details). If found, it reuses the existing template instead of creating a duplicate.

Simplified Workflow

Instead of making two separate API calls (Create Template + Grant to Player), you make one call. This reduces network overhead, processing time, and potential for errors between operations.

Use Cases

This endpoint is ideal for:

  • Welcome bonuses — Creating and immediately granting a bonus when a new player registers
  • Promotional campaigns — Instantly rewarding players with free spins during special events
  • Player incentives — Immediate bonus grants as part of VIP programs or loyalty rewards
  • One-time offers — Single-player, single-game bonuses that do not require template reuse
Info

For scenarios requiring multiple games or multiple players, use the traditional Create FRB Template and Grant FRB to Players endpoints instead.

Get FRB Templates

Get FRB Templates

Retrieve a paginated list of FRB templates for a given operator.

Request endpoint: /frb/{version}/templates/{groove_operator_id}?subProvider=1&page=N&limit=N

Request Method: GET

Usage information:

Returns all FRB templates belonging to the specified operator. Results are paginated.

Note

This request requires an authorization token: Bearer authorization token.
Token Format: The authorization token must be Base64-encoded as follows:
AuthorizationToken = encode(back_office_email:back_office_password)

Info

When subProvider=1 is set, only templates that were created through the standard flow are returned. Each template entry shows providerName and providerId reflecting the provider used at creation time.

Request parameters:

Parameter Data type Description
version String required The API version. Only version 1.0 is currently supported. Other version values are accepted, but are treated as 1.0.
Example: v1
groove_operator_id Integer required Groove operator ID (path parameter).
subProvider Integer required Must be 1. Ensures each template in the response shows the correct providerName and providerId.
page Integer optional Page number for pagination (1-based). Defaults to 1.
limit Integer optional Number of templates per page. Defaults to 10.
Authorization Yes (Header) Sinatra back office user

Example Response

Success response

{
  "templates": [
    {
      "id": "663b1f77bcf86cd799439044",
      "done": true,
      "offer_names": ["WelcomeBonus"],
      "succeeded_providers": ["BetSoft"],
      "failed_providers": [],
      "succeeded_insertion": [
        {
          "id": "663b1f77bcf86cd799439045",
          "templateId": "TMP_82600118_11_BetSoft",
          "providerName": "BetSoft",
          "providerId": 82,
          "operatorId": 11,
          "transactionId": "",
          "numberOfRounds": 10,
          "availableFromDate": "2026-04-29 00:00:00",
          "availableDuration": 7,
          "expirationDate": "2026-05-06 00:00:00",
          "offerName": "WelcomeBonus",
          "gameInfoList": [
            {
              "gameId": "82600118",
              "betAmount": [100]
            }
          ],
          "exceptionResponses": [],
          "players": []
        }
      ],
      "failed_insertion": []
    },
    {
      "id": "663b1f77bcf86cd799439055",
      "done": true,
      "offer_names": ["SummerPromo"],
      "succeeded_providers": ["Wazdan"],
      "failed_providers": [],
      "succeeded_insertion": [
        {
          "id": "663b1f77bcf86cd799439056",
          "templateId": "TMP_95000012_11_Wazdan",
          "providerName": "Wazdan",
          "providerId": 95,
          "operatorId": 11,
          "transactionId": "",
          "numberOfRounds": 5,
          "availableFromDate": "2026-04-29 00:00:00",
          "availableDuration": 14,
          "expirationDate": "2026-05-13 00:00:00",
          "offerName": "SummerPromo",
          "gameInfoList": [
            {
              "gameId": "95000012",
              "betAmount": [50]
            }
          ],
          "exceptionResponses": [],
          "players": []
        }
      ],
      "failed_insertion": []
    }
  ],
  "page": 1,
  "limit": 10,
  "total": 2
}
Info
  • templates is the paginated list. Each entry has the same structure as the response from the Create FRB Template endpoint.
  • providerName and providerId in each succeeded_insertion entry reflect the provider used when the template was created.
  • page, limit, and total fields support client-side pagination.

Error Response:

{
  "errMsg": "bad request"
}

Response codes:

Code Status Message
200 success Templates retrieved
400 bad request bad request
403 forbidden access forbidden access
500 internal server error internal server error

Sport Free Bets (Digitain and Betby)

Sport Free Bets (Digitain and Betby)

Grant, check and cancel free bets on a sportsbook provider. Two sportsbook providers are supported: Digitain and Betby.

All three endpoints are the same for both providers. What changes is the set of fields you send.

Operation Endpoint Method
Grant a sport free bet /frb/sport-free-bet POST
Get sport free bet status /frb/sport-free-bet/status?operator_id=XXXXX POST
Cancel a sport free bet /frb/sport-free-bet/cancel POST
Note

These requests require an authorization token: Bearer authorization token.
Token Format: The authorization token must be Base64-encoded as follows:
AuthorizationToken = encode(back_office_email:back_office_password)

Digitain or Betby: what is different

Topic Digitain Betby
providerName Digitain Betby, spelled exactly like this
Where the rules live In the request (odds, cash out, bet type, selections, duration) In a Betby template, created in the Betby back office before granting
templateId Do not send Required. The ID of the template from the Betby back office
Free bet amount minBet minBet, in the player’s currency, up to 2 decimals, at least 0.01
duration Required, greater than 0 (minutes) Optional. The validity set in the Betby template applies
Odds and rules fields Required (see below) Not needed. If sent, they are ignored
Players per request One One
Info

Betby templates are created in the Betby back office, not through the Groove API. Create the template there first, then send its ID as templateId in every grant. The template defines the bonus type, the allowed sports and markets, the odds limits and the validity period.

sequenceDiagram participant Operator as Casino Operator participant BetbyBO as Betby back office participant Groove as Groove Platform participant Betby Operator->>BetbyBO: Create a free bet template (one time) BetbyBO->>Operator: Template ID Operator->>Groove: POST /frb/sport-free-bet (providerName=Betby, templateId, minBet) Groove->>Betby: Give the bonus to the player Betby->>Groove: Bonus ID Groove->>Operator: status=Success, bonusId Note over Operator,Betby: The player places the free bet in the Betby sportsbook Operator->>Groove: POST /frb/sport-free-bet/status Groove->>Operator: Free bet status

Grant a sport free bet

Grant one free bet to one player.

Request endpoint: /frb/sport-free-bet

Request Method: POST

Request parameters:

Parameter Data type Digitain Betby Description
providerName String Required Required Digitain or Betby.
operatorId Integer Required Required Groove operator ID.
grooveGameId String Required Required The Groove game ID of the sportsbook for your brand.
playerId String Required Required The player ID.
playerCurrency String Required Required ISO 4217 currency code of the player.
playerCountry String Required Required Country code of the player.
playerCity String Required Required City of the player.
offerName String Required Required A name for the offer.
transactionId String Required Required Unique ID of this request, generated by the casino. A repeated transactionId returns the first result.
minBet Decimal Required Required The free bet amount. For Betby: at most 2 decimals, at least 0.01.
templateId String — Required Betby template ID from the Betby back office.
duration Integer Required Optional Validity in minutes. Digitain: greater than 0. Betby: not sent to Betby, the template validity applies.
userBonusTypeId Integer Required — Digitain bonus type ID.
maxCashOut Decimal Required — Maximum cash out. Greater than 0.
minTotalOdd Decimal Required — Minimum total odd. Greater than 0.
maxTotalOdd Decimal Required — Maximum total odd. Greater than 0 and not lower than minTotalOdd.
minWageringOdd Decimal Optional — Minimum wagering odd. Not higher than maxWageringOdd.
maxWageringOdd Decimal Optional — Maximum wagering odd.
allowedBetTypeId Integer Optional — Allowed bet type.
minNumberOfSelections Integer Optional — Minimum number of selections in the bet.
oneTimeBet Boolean Optional — The free bet can be used in one bet only.
bonusEventTypeId Integer Optional — Bonus event type.
sportIds String Optional — Allowed sports.
tournamentIds String Optional — Allowed tournaments.
gameIds String Optional — Allowed events.
Authorization Header Required Required Sinatra back office user.

“—” means the field is not used for this provider. If you send it, it is ignored.

Request body: Betby

{
  "providerName": "Betby",
  "operatorId": 11,
  "grooveGameId": "XXXXXXXXX",
  "playerId": "player_001",
  "playerCurrency": "EUR",
  "playerCountry": "MT",
  "playerCity": "Valletta",
  "offerName": "Weekend free bet",
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "templateId": "2291845327163297792",
  "minBet": 5.00
}

Request body: Digitain

{
  "providerName": "Digitain",
  "operatorId": 11,
  "grooveGameId": "236000000",
  "playerId": "player_001",
  "playerCurrency": "EUR",
  "playerCountry": "MT",
  "playerCity": "Valletta",
  "offerName": "Weekend free bet",
  "transactionId": "550e8400-e29b-41d4-a716-446655440001",
  "userBonusTypeId": 2,
  "duration": 10080,
  "minBet": 5.00,
  "maxCashOut": 100,
  "minTotalOdd": 1.5,
  "maxTotalOdd": 10,
  "minWageringOdd": 1.5,
  "maxWageringOdd": 10,
  "allowedBetTypeId": 1,
  "minNumberOfSelections": 1,
  "oneTimeBet": true,
  "bonusEventTypeId": 1
}

Success response

The response has the same shape for both providers.

{
  "status": "Success",
  "data": {
    "status": "Success",
    "transactionId": "550e8400-e29b-41d4-a716-446655440000",
    "bonusId": "2291846012345678901"
  }
}

Keep bonusId. You need it to check the status and to cancel the free bet.

When the provider rejects the grant, the HTTP code is still 200. data.status is Failed and data.exceptionResponses holds the reason:

{
  "status": "Success",
  "data": {
    "status": "Failed",
    "transactionId": "550e8400-e29b-41d4-a716-446655440000",
    "exceptionResponses": ["betby external api config is not available for this casino"]
  }
}

Get sport free bet status

Get the free bets granted to a player.

Request endpoint: /frb/sport-free-bet/status?operator_id=XXXXX

Request Method: POST

Request parameters:

Parameter Data type Description
operator_id Integer required Groove operator ID (query string).
providerName String required Digitain or Betby. Must be the provider used for the grant.
playerId String required The player ID.
freeBetIds Array optional The bonusId values from the grant response. Empty returns the player’s free bets.
currency String optional ISO 4217 currency code of the player.
Authorization Header Sinatra back office user.

Request body:

{
  "providerName": "Betby",
  "playerId": "player_001",
  "freeBetIds": ["2291846012345678901"],
  "currency": "EUR"
}

Success response

{
  "status": "Success",
  "data": {
    "items": [
      {
        "free_bet_id": "2291846012345678901",
        "player_id": "player_001",
        "casino_id": 11,
        "currency": "EUR",
        "number_of_spins": 1,
        "spins_used": 0,
        "bet_amount": "5",
        "status": "active",
        "expiration_date": "2026-10-30T00:00:00Z",
        "created_at": "2026-09-30T10:00:00Z"
      }
    ]
  }
}

Status Index:

Status Description Betby status
active The free bet is available. The player can use it. new, active
completed The player used the free bet. activated, done
expired The free bet was not used before the expiration date. expired
canceled The operator canceled the free bet. revoked
Note

For Betby, the status of an active free bet is read from Betby on every request. If Betby does not answer, the last known status is returned.

Cancel a sport free bet

Cancel a free bet the player has not used yet. The request is the same for both providers. You do not need to send providerName: Groove finds the provider from the original grant.

Request endpoint: /frb/sport-free-bet/cancel

Request Method: POST

Request parameters:

Parameter Data type Description
operatorId Integer required Groove operator ID.
grooveGameId String required The Groove game ID of the sportsbook for your brand.
items Array required The free bets to cancel.
items[].bonus_id String required The bonusId from the grant response.
items[].player_id String required The player ID.
items[].request_id Integer optional Your ID for this cancel item.
Authorization Header Sinatra back office user.

Request body:

{
  "operatorId": 11,
  "grooveGameId": "XXXXXXXXX",
  "items": [
    {
      "bonus_id": "2291846012345678901",
      "player_id": "player_001",
      "request_id": 1001
    }
  ]
}

Success response

{
  "status": "Success",
  "data": {
    "response_code": 0,
    "description": "",
    "bonus_id": "2291846012345678901",
    "player_id": "player_001",
    "request_id": 1001,
    "retryable": false
  }
}
Note

Only an unused free bet can be canceled. response_code other than 0 means the free bet was not canceled.

Betby cancel response codes

For Betby, response_code in the cancel response is one of these. retryable: true means you can send the same request again later.

Code Meaning Retryable
0 Canceled No
1005 Cannot be canceled: the free bet is not found, already used, or ended No
1007 Betby is not configured for this operator No
1100 Betby returned an error. See description No
1101 Betby is not available Yes
1102 Internal error Yes

How a Betby free bet reaches the wallet

When the player places a Betby bet with a bonus, Groove sends the normal Transaction API calls to the casino. Only bonus-money bets carry the bonus ID in frbid; the others are sent as normal real money bets.

Betby bonus type (back office name) bonus_type Wager amount sent to the casino frbid sent
Free bet (“bet refund”) freebet_refund 0 Yes
Free money (“free money”) freebet_freemoney 0 Yes
No risk bet (“no risk bet”) freebet_no_risk The real stake No
Combo boost comboboost The real stake No
Global combo boost global_comboboost The real stake No

Example from the Betby payout rules: a bet of 5 at odds 3.5.

Betby bonus type Wager sent If the bet wins If the bet loses
Free bet 0 12.50 (5 × 3.5 − 5) 0
Free money 0 17.50 (5 × 3.5) 0
No risk bet 5 17.50 (5 × 3.5) 5 (the stake returns)

For combo boost the win amount already includes the boost.

Wins, losses and rollbacks follow the same rule as their bet: frbid is sent only for freebet_refund and freebet_freemoney. Betby calculates every win amount, including the stake for free money and the boost for combo boost; Groove passes it to the casino as is.

Note

A combo boost bet keeps the normal round ID. To see that a round used a combo boost, open the round details: the bet and the win show “Combo boost” or “Global combo boost” with the multiplier.

Response codes

Code Status Message
200 success The request was processed. Check data for the result.
400 bad request The request body is not valid JSON.
403 forbidden access The user has no access to this operator.
422 unprocessable entity A required field is missing or not valid. The response lists each problem.
500 internal server error internal server error

Validation error example (Betby grant without templateId):

{
  "status": "Error",
  "data": ["template ID is required for provider betby"],
  "message": "sport free bet validation failed[template ID is required for provider betby]",
  "userFriendlyMessage": "sport free bet validation failed"
}

Get FRB currency values

Get FRB currency values

Returns the currency values used to calculate the FRB bet amount for each player currency. The player’s bet per spin is betAmount × betValue of the player’s currency.

Request endpoint: /frb/{version}/currency-data

Request Method: GET

Usage information:

This endpoint is read-only. It returns the same values that are used when a template is created and granted, so you can see the exact bet per spin before you grant a bonus.

Note

This request requires an authorization token: Bearer authorization token.
Token Format: The authorization token must be Base64-encoded as follows:
AuthorizationToken = encode(back_office_email:back_office_password)
A back office session token in the jwt-auth header is also accepted.

Request parameters:

Parameter Data type Description
version String required The API version. Only version 1.0 is currently supported. Other version values are accepted, but are treated as 1.0.
Example: 1

Example Response:

{
  "currencies": [
    { "currency": "ARS", "betValue": 1 },
    { "currency": "BRL", "betValue": 0.05 },
    { "currency": "CAD", "betValue": 0.01 },
    { "currency": "EUR", "betValue": 0.01 },
    { "currency": "INR", "betValue": 0.5 },
    { "currency": "JPY", "betValue": 1 },
    { "currency": "TRY", "betValue": 0.1 },
    { "currency": "USD", "betValue": 0.01 }
  ]
}

The example shows only some of the currencies. The real response contains every configured currency, sorted by currency code.

Response parameters:

Parameter Data type Description
currencies Array List of all configured currencies.
currencies[].currency String ISO 4217 currency code.
Example: EUR
currencies[].betValue Number Value used to calculate the bet per spin in this currency.

Example calculation:

Currency betValue betAmount: 100 gives a bet per spin of
EUR 0.01 1.00 EUR
USD 0.01 1.00 USD
BRL 0.05 5.00 BRL
TRY 0.1 10.00 TRY
INR 0.5 50.00 INR
JPY 1 100 JPY
Info
  • betValue is a fixed value per currency, not a live exchange rate.
  • The betAmount you send is used only when a non-default bet amount is enabled for your casino. To enable it, contact your account manager. Otherwise, the game provider’s default bet amount is used.
  • A game may not support the exact amount. In that case, the closest bet amount the game supports is used.

Error Response:

{
  "error": "currency data unavailable"
}

Response codes:

Code Status Message
200 success Currency values returned
400 bad request authorization header missing
401 unauthorized invalid authorization token
500 internal server error currency data unavailable