Assign Bonus

Assign Bonus to Players

This endpoint receives player bonus assignment requests from Groove. When casino operators want to grant free spins to specific players on your games, Groove sends the assignment details to your platform.

Request Details (From Groove to Your Platform)

Method: POST
Endpoint: https://{your_domain}/frb/assign (or your specified endpoint)
Content-Type: application/json; charset=UTF-8
Direction: Groove → Your Platform

Request Parameters (What You’ll Receive from Groove)

Parameter	Type	Mandatory	Description
`templateId`	string	Yes	Template’s ID (from create response)
`providerName`	string	Yes	Provider’s name
`operatorId`	int	Yes	Operator’s ID
`transactionId`	string	Yes	Transaction’s ID
`numberOfRounds`	int	Yes	Amount of free bets
`availableFromDate`	string	Yes	Date and time from which the bonus becomes available in UTC
`availableDuration`	int	Yes	How long the rounds will be available (in days)
`expirationDate`	string	Yes	Date and time until which the bonus is available in UTC
`balanceTypeId`	int	Yes	Defines if the money goes to bonus/real
`messageFirstLine`	string	Yes	Text message 1
`messageSecondLine`	string	Yes	Text message 2
`offerName`	string	Yes	Name of the offer
`gameInfoList`	array	Yes	Array with the game details
`gameInfoList.gameId`	string	Yes	Identifies specific game
`gameInfoList.betAmount`	decimal	Yes	Bet value for each free bet
`players`	array	Yes	Array with the player details
`players.playerId`	string	Yes	Player’s ID on operator’s side
`players.playerCurrency`	string	Yes	Player’s currency in ISO3 format
`players.playerCountry`	string	Yes	Player’s country in ISO3 format

Request Example

{
    "templateId": "fe06efeb-b7fd-4249-a58d-717226507d5f",
    "providerName": "Provider Name",
    "operatorId": 11,
    "transactionId": "292c8dbb-e00d-4807-a754-0b9ae5297c1j",
    "numberOfRounds": 10,
    "availableFromDate": "2023-06-19 14:56:56",
    "availableDuration": 90,
    "expirationDate": "2025-01-15 11:24:38",
    "balanceTypeId": 1,
    "messageFirstLine": "You got a Free Round Bonus",
    "messageSecondLine": "It's your lucky day",
    "offerName": "2e10691304314db08244f8c730055af73781878195",
    "gameInfoList": [
        {
            "gameId": "provider_game_id",
            "betAmount": 1
        }
    ],
    "players": [
        {
            "playerId": "12345678",
            "playerCurrency": "EUR",
            "playerCountry": "IRL"
        }
    ]
}

Response Examples

Success Response

{
    "code": 200,
    "status": "Success",
    "templateId": "assign_unique_456xyz",  // Unique ID for THIS assignment (different from create templateId)
    "players": [
        {
            "playerId": 793918407,
            "playerCurrency": "EUR",
            "playerCountry": "IRL"
        },
        {
            "playerId": 793918408,
            "playerCurrency": "EUR",
            "playerCountry": "IRL"
        }
    ],
    "exceptionResponses": null
}

**IMPORTANT - Unique Assignment IDs**: - Each `/assign` request must return a **unique templateId** in the response - This is different from the templateId received in the `/create` request - The unique assignment templateId allows casinos to track different bonus triggers (e.g., registration bonus vs deposit bonus) - This unique assignment templateId will be used as the `frbid` parameter in transaction requests - Example: Same bonus template assigned twice to same player should return two different templateIds

Partially Success Response

When some players are assigned successfully but others fail:

{
    "code": 200,
    "status": "Partially Succeeded",
    "templateId": "123abc456",
    "players": [
        {
            "playerId": 793918407,
            "playerCurrency": "EUR",
            "playerCountry": "IRL"
        }
    ],
    "exceptionResponses": null
}

Error Responses

General Error

{
    "status": "General Error",
    "code": 400,
    "templateId": null,
    "players": [
        {
            "playerId": 793918407,
            "playerCurrency": "EUR",
            "playerCountry": "IRL"
        }
    ],
    "exceptionResponses": "Invalid Parameters"
}

Wrong Game ID

{
    "status": "Wrong Game ID",
    "code": 443,
    "templateId": null,
    "players": [
        {
            "playerId": 793918407,
            "playerCurrency": "EUR",
            "playerCountry": "IRL"
        }
    ],
    "exceptionResponses": "Game id 123 is not valid"
}

Wrong Player ID

{
    "status": "Wrong Player Id",
    "code": 444,
    "templateId": null,
    "players": [
        {
            "playerId": 793918407,
            "playerCurrency": "EUR",
            "playerCountry": "IRL"
        }
    ],
    "exceptionResponses": ""
}

Internal Error

{
    "status": "Internal Error",
    "code": 500,
    "templateId": null,
    "players": [
        {
            "playerId": 793918407,
            "playerCurrency": "EUR",
            "playerCountry": "IRL"
        }
    ],
    "exceptionResponses": null
}

Implementation Requirements

Template Validation: Verify the templateId in the request matches a template previously created by Groove
Generate Unique Assignment ID: Create a new unique templateId for each assignment (different from the create templateId)
Currency Conversion: Your system must convert bet amounts from EUR to each player’s currency
Bet Value Mapping: After currency conversion, use the closest bet value supported by your game for that currency
Bulk Processing: Handle multiple player assignments in a single request from Groove
Partial Success Handling: Support partial success - some players may succeed while others fail
Player Validation: Check if player IDs from Groove exist in your system
Assignment Tracking: Store each unique assignment with its generated templateId for transaction reference
Idempotency: If Groove resends the same transactionId, return the original response with the same unique templateId

Processing the Request (Your Implementation)

// Example of how to process the incoming assignment request from Groove
app.post('/frb/assign', (req, res) => {
    const {
        templateId,
        transactionId,
        players,
        gameInfoList,
        // ... other parameters
    } = req.body;
    
    // Check if template exists (created earlier by Groove)
    const template = getTemplate(templateId);
    if (!template) {
        return res.status(400).json({
            status: "General Error",
            code: 400,
            templateId: null,
            players: players,
            exceptionResponses: "Template not found"
        });
    }
    
    // Generate a UNIQUE assignment ID for this specific assignment
    // This is different from the templateId in the request
    const uniqueAssignmentId = generateUniqueAssignmentId();
    // Example: "assign_" + uuid() or "assign_" + timestamp + "_" + randomId
    
    // Process each player
    const successfulPlayers = [];
    const failedPlayers = [];
    
    for (const player of players) {
        // Validate player exists in your system
        if (!validatePlayer(player.playerId)) {
            failedPlayers.push(player);
            continue;
        }
        
        // Convert EUR bet amounts to player's currency
        // and map to closest supported bet value
        const convertedBets = convertBetAmounts(
            gameInfoList,
            player.playerCurrency
        );
        
        // Map to closest supported bet values for the game
        const supportedBets = mapToSupportedBetValues(
            convertedBets,
            player.playerCurrency
        );
        
        // Assign bonus to player with the unique assignment ID
        assignBonusToPlayer({
            playerId: player.playerId,
            originalTemplateId: templateId,  // Store original for reference
            assignmentId: uniqueAssignmentId,  // Unique ID for this assignment
            convertedBets: supportedBets,
            expirationDate: req.body.expirationDate
        });
        
        successfulPlayers.push(player);
    }
    
    // Return appropriate response to Groove with UNIQUE assignment ID
    if (successfulPlayers.length === players.length) {
        res.json({
            code: 200,
            status: "Success",
            templateId: uniqueAssignmentId,  // Return the UNIQUE assignment ID
            players: successfulPlayers,
            exceptionResponses: null
        });
    } else if (successfulPlayers.length > 0) {
        res.json({
            code: 200,
            status: "Partially Succeeded",
            templateId: uniqueAssignmentId,  // Return the UNIQUE assignment ID
            players: successfulPlayers,
            exceptionResponses: null
        });
    } else {
        res.status(444).json({
            status: "Wrong Player Id",
            code: 444,
            templateId: null,
            players: failedPlayers,
            exceptionResponses: "No valid players found"
        });
    }
});

Validation Checklist

When processing assignment requests from Groove:

✅ Template ID exists in your system (from previous create request)
✅ All player IDs are validated against your player database
✅ Currency codes are in ISO3 format and supported
✅ Bet amounts are converted from EUR to player currencies
✅ Transaction ID hasn’t been processed before (idempotency)
✅ Expiration date hasn’t passed

Parameter Mismatch Handling

If the assignment parameters from Groove don’t match the stored template (except availableFromDate), return an error response:

{
    "status": "General Error",
    "code": 400,
    "templateId": null,
    "players": [...],
    "exceptionResponses": "Transaction parameter mismatch"
}

Currency Conversion Example

When Groove sends a template with EUR bet amounts, convert for each player:

Template (EUR)	Player Currency	Converted Amount
1.00 EUR	USD	1.10 USD
1.00 EUR	GBP	0.85 GBP
1.00 EUR	EUR	1.00 EUR

Important: After converting the EUR amount to the player’s currency, use the closest bet value supported by your game for that currency. For example, if the conversion results in 1.13 USD but your game only supports 1.00 or 1.25 USD bets, use the closest supported value.