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 Tech Fusion 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 Tech Fusion 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] 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

Free Round Bonus Process Flow

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

sequenceDiagram participant Casino as Casino Operator participant Tech Fusion as Tech Fusion Platform participant Game as Game Provider participant Player Casino->>Tech Fusion: Create FRB Template Tech Fusion->>Casino: Template ID Response Casino->>Tech Fusion: Grant FRB to Player Tech Fusion->>Casino: FRB Assignment Confirmation Player->>Casino: Login & Launch Game Tech Fusion->>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->>Tech Fusion: Wager Request (amount=0) Tech Fusion->>Casino: Forward Wager Request Casino->>Tech Fusion: Wager Response Tech Fusion->>Game: Forward Response Game->>Player: Display Spin Outcome Game->>Tech Fusion: Result Request (win amount) Tech Fusion->>Casino: Forward Result Request Casino->>Tech Fusion: Result Response Tech Fusion->>Game: Forward Response Game->>Player: Display Win & Updated Balance end Casino->>Tech Fusion: Get FRB Status Request Tech Fusion->>Casino: FRB Status Response alt Unused FRB Expiration Casino->>Tech Fusion: Cancel FRB Request Tech Fusion->>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 Tech Fusion 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
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 TechFusion 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 TechFusion.
  • 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
Note
  • Bet amount definition is in EUR cents, so for other currencies, we have conversion rates defined in the service.
  • Bet amount definition is in cents, so if the bet amount is 1.00, the value should be 100.
  • By default we will use the value of 0.01 as the minimum bet amount.
  • If any other value is required, please contact us and we will configure it. It should be defined in the betAmount array.
  • Amount set in game might be different than the amount set in the template (as different games might have different bet amounts set in them). We will use the closest bet amount to the bet amount set in the template.

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 value should be in cents.

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.

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 TechFusion 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 TechFusion 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 TechFusion 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 TechFusion.
  • For Playson providers, the template must contain only one game (automatically enforced by this endpoint).
Info
  • Bet amount definition is in EUR cents, so for other currencies, conversion rates are applied automatically.
  • Bet amount definition is in cents, so if the bet amount is 1.00, the value should be 100.
  • By default, a minimum bet amount of 0.01 (1 cent) is used.
  • If useDefaultAmount is set to true, the system will use the default bet amount configured for the casino.
  • The bet amount set in the game might differ from the template bet amount (as different games have different bet amounts). The closest bet amount to the template value will be 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 TechFusion
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, uses the default bet amount configured for the casino. If false or omitted, uses the bet amounts specified in games array. 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 in EUR cents (e.g., [100] for 1.00 EUR). 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 values should be specified in cents (e.g., 100 = 1.00 EUR).
  • Currency conversions are handled automatically based on configured exchange rates.
  • 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 in cents
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 TechFusion 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