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

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.

Request endpoint: /frb/games/{version}/metadata

Request Method: GET

Usage information for QuickFire

Game provider QuickFire requires a parameter named balanceTypeId. This parameter is not used by any other game provicer.

The valid values of the balanceTypeId parameter are:

  • 0: Real money
  • 1: Bonus money

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.0

Response Parameters:

None.

Example Response:

{
  "Quickfire": {
    "providerId": "27",
    "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"
      },
      "balanceTypeId": {
        "type": "Integer",
        "allowedValues": [
          0,
          1
        ]
      },
      "messageFirstLine": {
        "type": "String",
        "optional": false
      },
      "messageSecondLine": {
        "type": "String",
        "optional": false
      },
      "offerName": {
        "type": "String",
        "optional": false
      }
    },
    "gameInfoList": [
      {
        "gameId": "83400088",
        "betAmount": [
          0
        ]
      },
      {
        "gameId": "83400091",
        "betAmount": [
          0
        ]
      },
      {
        "gameId": "83400161",
        "betAmount": [
          0
        ]
      }
    ]
  },
  "Playson": {
    "providerId": "7",
    "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"
      },
      "balanceTypeId": {
        "type": "Integer",
        "allowedValues": [
          0,
          1
        ]
      },
      "messageFirstLine": {
        "type": "String",
        "optional": false
      },
      "messageSecondLine": {
        "type": "String",
        "optional": false
      },
      "offerName": {
        "type": "String",
        "optional": false
      }
    },
    "gameInfoList": [
      {
        "gameId": "80700000",
        "betAmount": [
          0
        ]
      },
      {
        "gameId": "80700023",
        "betAmount": [
          0
        ]
      }
    ]
  },
  "Evoplay Entertainment": {
    "providerId": "23",
    "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"
      },
      "balanceTypeId": {
        "type": "Integer",
        "allowedValues": [
          0,
          1
        ]
      },
      "messageFirstLine": {
        "type": "String",
        "optional": false
      },
      "messageSecondLine": {
        "type": "String",
        "optional": false
      },
      "offerName": {
        "type": "String",
        "optional": false
      }
    },
    "gameInfoList": [
      {
        "gameId": "82500000",
        "betAmount": [
          0
        ]
      },
      {
        "gameId": "82500037",
        "betAmount": [
          0
        ]
      }
    ]
  }
}

Error Response:

{
  "errMsg": "unauthorized"
}

Response codes:

Code Status Message
200 success 200 success Got games providers FRB metadata successfully
400 bad request bad request
500 internal server error internal server error

Create FRB template

Create FRB template

Creates a new FRB template.

Request endpoint: /frb/create/{version}/template

Request Method: POST

Usage information

The request body includes the FRB templates to create.

Note

Starting of 2025-12-01, authorization token is required for this request. The authorization token must be Base64-encoded as follows:
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 Sinatra.
  • 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
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 Sinatra 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 closes 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: 1.0
Authorization Yes (Header) Sinatra back office user

Request Body

[
  {
    "providerName": "string",
    "operatorId": 0,
    "numberOfRounds": 0,
    "availableFromDate": "YYYY-MM-DD HH:mm:ss",
    "availableDuration": 0,
    "expirationDate": "YYYY-MM-DD HH:mm:ss",
    "balanceTypeId": [
      0
    ],
    "messageFirstLine": "string",
    "messageSecondLine": "string",
    "offerName": "string",
    "gameInfoList": [
      {
        "gameId": "string",
        "betAmount": [
          0
        ]
      }
    ]
  }
]
Note

betAmount value should be as cents.

The response body include the id parameter, which is used to get the template collection ID in the main object, which in turn is used to grant FRB.

Response Parameters:

None.

Example Response:

Success response:

{
  "createdBy": "string",
  "lastModifiedBy": "string",
  "version": 0,
  "id": "created_id",
  "done": true,
  "succeeded_insertion": [
    {
      "createdBy": "string",
      "lastModifiedBy": "string",
      "version": 0,
      "id": "string",
      "templateId": "string",
      "providerName": "string",
      "providerId": 0,
      "operatorId": 0,
      "currencyData": [
        {
          "name": "string",
          "bet_value": 0
        }
      ],
      "numberOfRounds": 0,
      "availableFromDate": "string",
      "availableDuration": 0,
      "expirationDate": "string",
      "balanceTypeId": [
        0
      ],
      "messageFirstLine": "string",
      "messageSecondLine": "string",
      "offerName": "string",
      "gameInfoList": [
        {
          "gameId": "string",
          "betAmount": [
            0
          ],
          "mobileGamePlatformInfo": {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
          },
          "desktopGamePlatformInfo": {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
          },
          "extraData": {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
          }
        }
      ],
      "exceptionResponses": [
        "string"
      ],
      "players": [
        {
          "playerId": "string",
          "playerCurrency": "string",
          "playerCountry": "string"
        }
      ],
      "status": "string",
      "koalaRequest": {
        "requestUri": "string",
        "requestBody": "string",
        "responseStatus": "string",
        "responseBody": "string"
      }
    }
  ]
}
Info
  • If the request is successful, the response will contain a list of successfully created templates ( succeeded_insertion).
  • Upon assigning the FRB template, the template id that should be sent is the “id” field of the template object in the response (root object), in this example it is “created_id”.

Error Response:

{
  "errMsg": "bad request"
}

Response codes:

Code Status Message
200 success 200 success Got games providers FRB metadata 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

Grant FRB to players

Grant FRB to players

Grant a free round bonus to a player.

Request endpoint: /frb/grant/{version}/players

Request Method: POST

Usage information:

The request body includes the FRB template to granted to the specified players.

Note

Starting of 2025-12-01, authorization token is required for this request. The authorization token must be Base64-encoded as follows:
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

Template ID should be the ID of the FRB template created in the Create FRB template endpoint.

In the response body, parameter templateId is used to get the FRB templates granted successfully to players from the succeededAwarded parameter list under the FrbTemplatesAwardedCollections object.

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.0
Authorization Yes (Header) Sinatra back office user

Request body:

body includes FRB template to be granted to specific players.

{
  "templateId": "string",
  "transactionId": "string",
  "players": [
    {
      "playerId": "string",
      "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.
  • 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": "string",
  "templateId": "string",
  "players": [
    {
      "playerId": "string",
      "playerCurrency": "string",
      "playerCountry": "string"
    }
  ],
  "status": "string",
  "templatesAwardedCollections": {
    "failed_frb_awarded": [],
    "succeeded_frb_awarded": [
      {
        "templateId": "success_template_id",
        "providerName": "string",
        "players": [
          {
            "playerId": "string",
            "playerCurrency": "string",
            "playerCountry": "string"
          }
        ],
        "status": "string"
      }
    ],
    "partially_frb_awarded": []
  }
}
Info

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

Info

For Get / Cancel FRB requests, the id which should be sent is the template id within succeeded_frb_awarded, in this case “success_template_id”.

Error Response:

{
  "errMsg": "bad request"
}

Response codes:

Code Status Message
200 success 200 success Got games providers FRB metadata 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 for the supported providers.

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

Request Method: GET

Usage information:

The request query parameters includes 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 Mandatory Description
version Yes The API version. Only version 1.0 is currently supported. Other version values are accepted, but are treated as 1.0.
Example: 1.0
operator_id Yes Groove operator id
template_id Yes FRB grant template id.
player_id Yes The granted player id.
Authorization Yes (Header) Sinatra back office user

Example Response

Success response

{
  "player_id": "12345",
  "player_currency": "EUR",
  "operator_id": 67890,
  "provider_id": 123,
  "status": "active",
  "template_id": "template567",
  "left_rounds": 10,
  "total_rounds": 50,
  "expiration_date": "2025-02-11T12:00:00Z",
  "games": [
    {
      "game_id": "game001",
      "bet_amount": [
        10.5,
        20
      ],
      "currency": "EUR"
    },
    {
      "game_id": "game002",
      "bet_amount": [
        10.5,
        20
      ],
      "currency": "EUR"
    }
  ],
  "error_message": ""
}

Error Response:

 {
  "player_id": "12345",
  "player_currency": "EUR",
  "operator_id": 67890,
  "provider_id": 123,
  "template_id": "template567",
  "expiration_date": "2025-02-11T12: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 for the supported providers.

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

Request Method: DELETE

Usage information:

The request query parameters includes 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 Mandatory Description
version Yes The API version. Only version 1.0 is currently supported. Other version values are accepted, but are treated as 1.0.
Example: 1.0
operator_id Yes Groove operator id
template_id Yes FRB grant template id.
player_id Yes The granted player id.
Authorization Yes (Header) Sinatra back office user

Example Response

Success response

{
  "player_id": "12345",
  "player_currency": "EUR",
  "operator_id": 67890,
  "provider_id": 123,
  "status": "active",
  "template_id": "template567",
  "left_rounds": 10,
  "total_rounds": 50,
  "expiration_date": "2025-02-11T12:00:00Z",
  "games": [
    {
      "game_id": "game001",
      "bet_amount": [
        10.5,
        20
      ],
      "currency": "EUR"
    },
    {
      "game_id": "game002",
      "bet_amount": [
        10.5,
        20
      ],
      "currency": "EUR"
    }
  ],
  "error_message": ""
}

Error Response:

 {
  "player_id": "12345",
  "player_currency": "EUR",
  "operator_id": 67890,
  "provider_id": 123,
  "template_id": "template567",
  "expiration_date": "2025-02-11T12: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

Warning

DRAFT - Testing in Progress This endpoint is currently in draft status and undergoing testing. The API specification and behavior may change before final release. Please use with caution in production environments.

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

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

Starting of 2025-12-01, authorization token is required for this request. The authorization token must be Base64-encoded as follows:
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 Sinatra.
  • 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 defined in the Sinatra service.
  • 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: 1.0
Authorization Yes (Header) Sinatra back office user

Request Body

{
  "providerName": "Quickfire",
  "operatorId": 123,
  "playerId": "PLAYER_456",
  "playerCurrency": "USD",
  "playerCountry": "US",
  "offerName": "WELCOME_BONUS_001",
  "numberOfRounds": 5,
  "availableDuration": 30,
  "useDefaultAmount": false,
  "templateId": "TMP_9876543210fedcba",
  "transactionId": "TXN_1234567890abcdef",
  "games": [
    {
      "gameId": "GAME_123",
      "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 that must be configured in Sinatra
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
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 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 by the Sinatra service 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": "507f1f77bcf86cd799439011",
  "status": "Success",
  "template": {
    "templateId": "TMP_1234567890",
    "providerName": "Quickfire",
    "providerId": 27,
    "operatorId": 123,
    "transactionId": "550e8400-e29b-41d4-11e8-b566-0800200c9a66",
    "numberOfRounds": 5,
    "availableFromDate": "2024-01-01 10:00:00",
    "availableDuration": 30,
    "expirationDate": "2024-01-31 10:00:00",
    "offerName": "WELCOME_BONUS_001",
    "gameInfoList": [
      {
        "gameId": "GAME_123",
        "betAmount": [100]
      }
    ],
    "players": [
      {
        "playerId": "PLAYER_456",
        "playerCurrency": "USD",
        "playerCountry": "US"
      }
    ]
  },
  "grant": {
    "templateId": "TMP_1234567890",
    "transactionId": "550e8400-e29b-41d4-11e8-b566-0800200c9a66",
    "status": "Success",
    "message": "Template awarded successfully",
    "playerId": "PLAYER_456",
    "playerCurrency": "USD",
    "playerCountry": "US",
    "exceptionResponses": []
  }
}

Response Body Fields

Field Type Description
id string MongoDB ObjectID 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
template.providerId integer Internal provider 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 ISO 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 ISO datetime when the bonus expires (format: YYYY-MM-DD HH:mm:ss)
template.offerName string Bonus offer name
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:
  • The response includes both template creation details and grant confirmation in a single response.
  • If exceptionResponses contains entries, review them for warnings or partial failures.

Error Response:

{
  "error": "invalid request"
}

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
• User does not have access to specified operator
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:

  1. Create Template ✗
  2. Grant to Player ✗

You now make one call:

  1. Create and Grant ✓

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 don’t require template reuse

Comparison with Standard Flow

Aspect Standard Flow (Create + Grant) Create and Grant
API Calls 2 separate calls 1 unified call
Complexity Medium (must manage template ID between calls) Low (single operation)
Network Overhead Higher (2 round trips) Lower (1 round trip)
Error Handling Complex (can fail at either step) Simplified (atomic operation)
Idempotency Must be managed separately for each call Built-in for entire operation
Use Case Multiple players, multiple games, bulk operations Single player, single game, instant grant
Template Reuse Manual management Automatic detection

Example Workflow

sequenceDiagram participant Client as Casino Client participant API as Sinatra FRB API participant DB as Database participant Koala as Game Provider Client->>API: POST /frb/create/1.0.0/create-and-grant Note over Client,API: Single request with player, game, and bonus details API->>API: Validate request (games, rounds, player, etc.) API->>DB: Check for existing template alt Template Exists DB-->>API: Return existing template else Template Not Found API->>Koala: Create new template Koala-->>API: Template created API->>DB: Save template end API->>Koala: Grant template to player Koala-->>API: Grant successful API->>DB: Save grant record API-->>Client: Combined response (template + grant info) Note over Client,API: Single response with all details

Best Practices

  1. Idempotency Keys - Always provide templateId and transactionId for important operations to ensure idempotency
  2. Error Handling - Check both status field and grant.exceptionResponses array for any issues
  3. Single Game Limit - Remember this endpoint only supports one game per request
  4. Bet Amounts - Specify bet amounts in cents (e.g., 100 for 1.00 EUR)
  5. Player Currency - Ensure the player’s currency matches their actual account currency
  6. Template ID Storage - Store the returned grant.templateId for future status checks and cancellations
Tip

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