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.