This Provider API Endpoint enables an Operator to add promotional Free Bets to user accounts. By submitting relevant player information and Free Bet details, the API responds with confirmation statuses. The structured request and response formats make it easy for developers to integrate this promotional feature and manage user incentives effectively, restricting Free Bets to specific games and currency and specifying exact count of Free Bets to issue. When a Free Bet is placed, its Bet Amount is not withdrawn from the player's wallet, only Win Amount (if any) is credited to the player's wallet. Once a Free Bet is placed, it's consumed irrevocably. You can issue Free Bets to multiple players under one promotion via this API. Free Bets have expiry date, meaning they are automatically expired. Also Free Bets can be manually removed. If Free Bets are issued, they can be consumed by player until depletion as long as they are not removed nor expired.
/free-bets/add
Free Bets APIs are disabled by default. To enable this feature, please contact your account manager.
Operator calls this endpoint on the Provider to grant promotional Free Bets to specified players. In a safe, auditable, and idempotent way.
Multiple players can be issued Free Bets with this request, all associated with same specified promotion identified by promotionId.
Each player may receive Free Bets under a given promotionId only once. Applicable for this request and across all time (previously-issued Free Bets).
The promotion has some properties applicable to all Free Bets issued within said promotionId. Such as:
currency, restricting Free Bets placement to this currency.gameIds restricting Free Bets placement to these allowed games only.expiresAt which allows you to manually set expiry date for the issued Free Bets.Per-player uniqueness (hard rule): The combination of promotionId + playerId must be unique always. If any duplicate combination is detected, the entire request is rejected (no issuance). Uniqueness is checked for this request and across all time (previously-issued Free Bets).
Free Bets are pooled across games: Free Bets issued to player are shared by all specified games. If Free Bet was placed in one game by the player, it would affect Free Bets remaining balance in other games for this promotion and player.
Refer to Free Bets section to understand how Free Bets work.
Refer to Remove Free Bets section to understand how Free Bets are removed.
Refer to Free Bets Stats section to understand how Free Bets statistics are checked.
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 | Uniqueness | Description |
|---|---|---|---|---|
promotionId |
string | Yes | Unique per promotion | UUIDv4 unique identifier for the promotion associated with the Free Bets. |
promotionTitle |
string | No | Unique per promotion | Optional title for the promotion associated with these Free Bets. |
count |
number | Yes | May vary per request | Number of Free Bets to issue. Must be integer between 1 and 1000 inclusive. Shared across all games. |
currency |
string | Yes | May vary per request | Restrict issuance of Free Bets to this currency code (ISO 4217, uppercase). |
expiresAt |
string | No | May vary per request | Expiry date for issued Free Bets. ISO 8601 date-time string. Must be future date within next 30 days. Defaults to 30 days from issuance if omitted (UTC). |
gameIds |
Array<string> |
Yes | May vary per request | List of Game ID strings. Restrict issuance of Free Bets to these games. |
playerIds |
Array<string> |
Yes | Unique per promotion | List of Player Identifiers for players recipient of Free Bets. String Must not contain / character. Maximum of 100 items is accepted.Uniqueness Note: No duplicate Player IDs across all time (each Player ID string element). |
uniqueId |
string | Yes | Unique per request | Operator-generated UUIDv4. Returned in the API response. |
Response Body
| Key | Value Type | Required | Description |
|---|---|---|---|
status |
string | Yes | See AddFreeBetsResponseStatus. |
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. |
AddFreeBetsResponseStatus
| Status Code | Status | Description |
|---|---|---|
| 0 | OK |
All Free Bets were issued successfully. |
| 50 | INTERNAL_ERROR |
Some internal error happened within the Provider when trying to issue the Free Bets. |
| 56 | OPERATOR_IS_NOT_ENABLED |
Operator is not enabled. Please contact support. |
| 68 | DUPLICATE_FREE_BET |
Duplicate Free Bet issuance detected. None of the requested Free Bets were issued. |
| 70 | OPERATOR_FEATURE_DISABLED |
Operator feature is disabled. Please contact support. |
curl -X POST "https://< Provider API Base Path - Contact Technical Support >/free-bets/add" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "authorization: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" \
--data '{
"promotionId": "sample-promotion-id-100",
"count": 5,
"currency": "GBP",
"expiresAt": "2026-12-31T23:59:59Z",
"gameIds": [
"1001"
],
"playerIds": [
"sample-player-id-10",
"sample-player-id-20"
],
"uniqueId": "5E2AD325-1C57-41BA-AD23-D6D34B32A63A"
}'
Request Body
{
"promotionId": "sample-promotion-id-100",
"count": 5,
"currency": "GBP",
"expiresAt": "2026-12-31T23:59:59Z",
"gameIds": ["1001"],
"playerIds": ["sample-player-id-10", "sample-player-id-20"],
"uniqueId": "5E2AD325-1C57-41BA-AD23-D6D34B32A63A"
}
OK
{
"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"
}
DUPLICATE_FREE_BET
{
"status": "DUPLICATE_FREE_BET",
"statusCode": 68,
"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"
}