Get FRB Status

This endpoint allows Groove to query the status of a specific free round bonus assignment for a player on your platform.

Request Details (From Groove to Your Platform)

Method: GET
Endpoint: https://{your_domain}/frb/{version}/bonus?operator_id={operator_id}&template_id={template_id}&player_id={player_id}
Direction: Groove → Your Platform

Request Parameters (What You’ll Receive from Groove)

Parameter	Type	Mandatory	Description
`version`	String	Yes	The API version. Currently supports 1.0 Example: `1.0`
`operator_id`	Integer	Yes	Groove operator ID Example: `11`
`template_id`	String	Yes	The unique assignment ID (the one your platform generated during /assign) Example: `assign_456xyz`
`player_id`	String	Yes	The player ID Example: `12345678`

Request Example

GET /frb/1.0/bonus?operator_id=11&template_id=assign_456xyz&player_id=12345678

Response Parameters (What You Must Return)

Parameter	Type	Mandatory	Description
`player_id`	String	Yes	The player ID from the request
`player_currency`	String	Yes	Player’s currency in ISO3 format
`operator_id`	Integer	Yes	The operator ID from the request
`provider_id`	Integer	Yes	Your provider ID
`status`	String	Yes	Current status of the bonus (see Status Index below)
`template_id`	String	Yes	The assignment ID from the request
`left_rounds`	Integer	Conditional*	Number of rounds remaining *Required if status is `active`
`total_rounds`	Integer	Conditional*	Total number of rounds originally granted *Required if status is `active`
`expiration_date`	String	Yes	Expiration date in ISO 8601 format Example: `2025-02-11T12:00:00Z`
`games`	Array	Conditional*	List of games for this bonus *Required if status is `active`
`games.game_id`	String	Yes	Game identifier
`games.bet_amount`	Array	Yes	Available bet amounts in player’s currency
`games.currency`	String	Yes	Currency for the bet amounts
`error_message`	String	No	Error description (empty string if no error)

Available Statuses

All FRB endpoints must use these exact status values:

Status Value	Description
`"active"`	The FRB is active and can be used by the player
`"canceled"`	The FRB has been canceled by the operator
`"expired"`	The FRB has passed its expiration date
`"completed"`	The player has used all available rounds

**Note**: These are the only valid status values. Always use lowercase and return them as strings.

Response Examples

Success Response - Active Bonus

{
    "player_id": "12345678",
    "player_currency": "EUR",
    "operator_id": 11,
    "provider_id": 123,
    "status": "active",
    "template_id": "assign_456xyz",
    "left_rounds": 10,
    "total_rounds": 50,
    "expiration_date": "2025-02-11T12:00:00Z",
    "games": [
        {
            "game_id": "game001",
            "bet_amount": [1.0, 2.0],
            "currency": "EUR"
        },
        {
            "game_id": "game002",
            "bet_amount": [1.0, 2.0],
            "currency": "EUR"
        }
    ],
    "error_message": ""
}

Success Response - Completed Bonus

{
    "player_id": "12345678",
    "player_currency": "EUR",
    "operator_id": 11,
    "provider_id": 123,
    "status": "completed",
    "template_id": "assign_456xyz",
    "left_rounds": 0,
    "total_rounds": 50,
    "expiration_date": "2025-02-11T12:00:00Z",
    "games": [],
    "error_message": ""
}

Error Response

{
    "player_id": "12345678",
    "player_currency": "EUR",
    "operator_id": 11,
    "provider_id": 123,
    "template_id": "assign_456xyz",
    "expiration_date": "2025-02-11T12:00:00Z",
    "error_message": "Bonus not found"
}

HTTP Response Codes

Code	Status	Description
200	Success	FRB status retrieved successfully
400	Bad Request	Invalid parameters
403	Forbidden	Access denied
500	Internal Server Error	Server error occurred

Implementation Example

app.get('/frb/:version/bonus', (req, res) => {
    const { operator_id, template_id, player_id } = req.query;
    const { version } = req.params;
    
    // Validate parameters
    if (!operator_id || !template_id || !player_id) {
        return res.status(400).json({
            player_id: player_id || "",
            player_currency: "",
            operator_id: parseInt(operator_id) || 0,
            provider_id: 123,
            template_id: template_id || "",
            expiration_date: "",
            error_message: "Missing required parameters"
        });
    }
    
    // Look up the bonus assignment
    const assignment = getAssignment(template_id, player_id);
    
    if (!assignment) {
        return res.status(404).json({
            player_id: player_id,
            player_currency: "EUR",
            operator_id: parseInt(operator_id),
            provider_id: 123,
            template_id: template_id,
            expiration_date: "",
            error_message: "Bonus not found"
        });
    }
    
    // Determine status
    let status = 'active';
    if (assignment.canceled) {
        status = 'canceled';
    } else if (new Date(assignment.expiration_date) < new Date()) {
        status = 'expired';
    } else if (assignment.left_rounds === 0) {
        status = 'completed';
    }
    
    // Build response
    res.json({
        player_id: player_id,
        player_currency: assignment.player_currency,
        operator_id: parseInt(operator_id),
        provider_id: 123,
        status: status,
        template_id: template_id,
        left_rounds: assignment.left_rounds,
        total_rounds: assignment.total_rounds,
        expiration_date: assignment.expiration_date,
        games: status === 'active' ? assignment.games : [],
        error_message: ""
    });
});

Important Notes

Template ID: The template_id in the request is the unique assignment ID your platform generated during the /assign request
Status Logic: Determine status based on cancellation, expiration, and remaining rounds
Games Array: Only include games array when status is active
Bet Amounts: Return the converted bet amounts in the player’s currency
Error Handling: Always return a structured response even for errors

Best Practices

Cache Assignment Data: Keep assignment data readily available for quick status checks
Track Round Usage: Accurately track remaining rounds as players use them
Update Status: Automatically update status based on expiration and usage
Validate Operator: Ensure the operator_id matches the assignment
Log Requests: Keep audit logs of all status check requests