This Provider API Endpoint provides statistics on Free Bets usage, enabling Operators to analyze the effectiveness of their promotional campaigns. By querying specific parameters, the API returns detailed usage metrics, allowing developers to refine promotional strategies based on user engagement and behavior analysis. This API reports promotional Free Bets that have been issued and consumed. Free Bets are reported for one promotion only.
/free-bets/stats
Free Bets APIs are disabled by default. To enable this feature, please contact your account manager.
Operator calls this endpoint on the Provider to report promotional Free Bets statistics of specified players.
Multiple players can have their Free Bets stats reported by this API:
promotionId.Refer to Free Bets section to understand how Free Bets work.
Refer to Add Free Bets section to understand how Free Bets are added.
Refer to Remove Free Bets section to understand how Free Bets are removed.
Request Headers
| Key | Value Type | Required | Description |
|---|---|---|---|
authorization |
string | Yes | API Authorization token |
Content-Type |
string | Yes | Strictly application/json |
Request Body
| Key | Value Type | Required | Description |
|---|---|---|---|
promotionId |
string | Yes | UUIDv4 unique identifier for the promotion associated with the Free Bets to report their statistics. |
playerIds |
Array<string> |
Yes | List of Player Identifiers for players whose Free Bets will be reported. String must not contain / character. Maximum of 100 items is accepted. |
uniqueId |
string | Yes | Operator-generated UUIDv4. Returned in the API response. |
Response Body
| Key | Value Type | Required | Description |
|---|---|---|---|
promotionId |
string | No | UUIDv4 unique identifier for the promotion associated with the Free Bets which statistics are reported in this response. |
playersStats |
Array<FreeBetsStatsResponseItem> |
No | See FreeBetsStatsResponseItem for more info. |
status |
string | Yes | See FreeBetsStatsResponseStatus. |
statusCode |
number | Yes | See ProviderResponseStatusCode reference. |
statusMessage |
string | No | Verbose human-friendly description of the status. |
success |
boolean | Yes | Indicates if the request was successfully processed. |
uniqueId |
string | Yes | Operator-generated UUIDv4. Same value from API request. |
FreeBetsStatsResponseItem
| Key | Value Type | Required | Description |
|---|---|---|---|
playerId |
string | Yes | Identifier of the player, whose Free Bets statistics are reported under this promotion. |
currency |
string | Yes | Free Bets issued under this promotion are restricted to this currency code (ISO 4217, uppercase). |
expiresAt |
string | Yes | Expiry date for issued Free Bets. ISO 8601 date-time string. |
freeBetsConsumed |
number | Yes | Number of Free Bets consumed by this player under this promotion. |
freeBetsIssued |
number | Yes | Number of Free Bets originally issued to this player under this promotion. |
gameIds |
Array<string> |
Yes | List of Game ID strings. Issuance of Free Bets is restricted to these games. |
issuedAt |
string | Yes | Issuance date of Free Bets. ISO 8601 date-time string. |
removedAt |
string | No | Removal date of Free Bets. ISO 8601 date-time string. |
FreeBetsStatsResponseStatus
| Status Code | Status | Description |
|---|---|---|
| 0 | OK |
Free Bets statistics were reported successfully. |
| 50 | INTERNAL_ERROR |
Some internal error happened within the Provider when trying to report the Free Bets. |
| 56 | OPERATOR_IS_NOT_ENABLED |
Operator is not enabled. Please contact support. |
| 70 | OPERATOR_FEATURE_DISABLED |
Operator feature is disabled. Please contact support. |
| 71 | PROMOTION_NOT_FOUND |
Promotion not found for requested promotionId. |
curl -X POST "https://< Provider API Base Path - Contact Technical Support >/free-bets/stats" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "authorization: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" \
--data '{
"promotionId": "sample-promotion-id-100",
"playerIds": [
"sample-player-id-10",
"sample-player-id-20"
],
"uniqueId": "5E2AD325-1C57-41BA-AD23-D6D34B32A63A"
}'
Request Body
{
"promotionId": "sample-promotion-id-100",
"playerIds": ["sample-player-id-10", "sample-player-id-20"],
"uniqueId": "5E2AD325-1C57-41BA-AD23-D6D34B32A63A"
}
OK
{
"promotionId": "sample-promotion-id-100",
"playersStats": [
{
"playerId": "sample-player-id-10",
"currency": "GBP",
"expiresAt": "2026-12-31T23:59:59Z",
"freeBetsConsumed": 5,
"freeBetsIssued": 5,
"gameIds": [
"1001"
],
"issuedAt": "2026-12-01T00:00:00Z"
},
{
"playerId": "sample-player-id-20",
"currency": "GBP",
"expiresAt": "2026-12-31T23:59:59Z",
"freeBetsConsumed": 3,
"freeBetsIssued": 5,
"gameIds": [
"1001"
],
"issuedAt": "2026-12-01T00:00:00Z"
}
],
"status": "OK",
"statusCode": 0,
"success": true,
"uniqueId": "5E2AD325-1C57-41BA-AD23-D6D34B32A63A"
}
INTERNAL_ERROR
{
"status": "INTERNAL_ERROR",
"statusCode": 50,
"success": false,
"uniqueId": "5E2AD325-1C57-41BA-AD23-D6D34B32A63A"
}
OPERATOR_IS_NOT_ENABLED
{
"status": "OPERATOR_IS_NOT_ENABLED",
"statusCode": 56,
"success": false,
"uniqueId": "5E2AD325-1C57-41BA-AD23-D6D34B32A63A"
}
OPERATOR_FEATURE_DISABLED
{
"status": "OPERATOR_FEATURE_DISABLED",
"statusCode": 70,
"success": false,
"uniqueId": "5E2AD325-1C57-41BA-AD23-D6D34B32A63A"
}
PROMOTION_NOT_FOUND
{
"status": "PROMOTION_NOT_FOUND",
"statusCode": 71,
"success": false,
"uniqueId": "5E2AD325-1C57-41BA-AD23-D6D34B32A63A"
}