Reward API

The Reward API offers methods for retrieving information or manipulating rewards. All requests, except /free-bet where the communication is established via the OPTIONS HTTP method, are passed from the operator to VeliGames using the POST HTTP method with the content type application/json.

The signature parameter in the header is mandatory for all requests. The only exception is making a request for free bet options. In this case, the signature parameter is omitted from the header.

See also

Authentication

API Method: free-bet

The operator makes a request to the free-bet endpoint to retrieve the free bet options for each provider. This request does not require any additional request parameters.

Path:

https://VELIGAMES_API_URL/reward-api/public/free-bet

HTTP Method:

OPTIONS

JSON Response (HTTP 200 OK)

An example of the free-bet API method

curl -X 'POST' \
'https://VELIGAMES_API_URL/reward-api/public/free-bet' \
-H 'accept: */*' \
-H 'signature:OPERATOR_ID:tapm5+EvNZ5dCCN...N5CdDx0GCfUspxw==' \
-H 'Content-Type: application/json' \
-d '{
     "freeBetOptions": {
        "provider1": {
           "betAmount": [{ "fieldName": "betAmount", "required": true }],
           "betPerLineAmount": [
              { "fieldName": "betPerLineAmount", "required": true },
              { "fieldName": "lines", "required": false }
           ]
        },
        "provider2": {
           "betLevel": [{ "fieldName": "betLevel", "required": true }]
        },
        "provider3": {
           "betAmount": [{"fieldName": "betAmount", "required": true}]
        }
      }
    }'

Tip

If a provider offers multiple options at the same level, you can specify either one group of parameters or another.

For example, in the scenario above, provider1 can choose to set either the betAmount group with one required field or the betPerLineAmount group, which contains one required and one optional field.

API Method: free-bet/assign

The operator can use this endpoint to assign free bets to a selected player.

Path:

https://VELIGAMES_API_URL/reward-api/public/free-bet/assign

HTTP Method:

POST

The following parameters are required. A request is only valid if it contains all of these parameters.

Parameter	Type	Description
freeBetId	string	One-time unique identifier generated by OPERATOR
providerId	string	Identifier of the game provider
gameId	string	The unique identifier of the game
playerId	string	The player’s unique identifier
currency	string	The player’s currency code
brandId	string	The identifier of the casino brand
endDate	string	The end date of the free bets end date (in UTC time zone)
quantity	string	The total quantity of free bets assigned to the player

Some parameters are specific to providers. If additional information is required it is placed in the config object. To see which provider specific parameters must be included, make a call to the /free-bet endpoint.

Parameter	Type	Purpose
config.betAmount	number	Bet amount per spin
config.betLevel	number	Bet Level
config.betPerLineAmount	number	Amount of bet per line (Relevant for some slot games)
config.lines	number	The total bet is calculated by other fields * lines. For example, betPerLineAmount * lines. The default value is 1.
config.denomination	number	The bet denomination, If omitted, the default denomination is based on the selected game.
config.coins	number	The number of coins. The value of this parameter must match the number of coins available in the selected game. If omitted, the effective default number of coins is used.

Successful response

Parameter	Type	Purpose
acknowledged	boolean	Reward request is added to the queue and will callback assignment status to operator.

Tip

When assigning a free bet to a player, VeliGames sends asynchronous requests to the provider. According to the pre-provider validation protocol, a successful response does not guarantee you will not get an error status response.

Error response

Parameter	Type	Purpose
error	enum	See Error types below.
details	object [fieldName]: ‘error description’	Optional description

Error Types

Error type	HTTP code	Description
UNKNOWN_ERROR	500	A generic error or an internal server error that can be retried
BAD_REQUEST	400	The parameters are either missing or invalid
UNAUTHORIZED	401	Invalid signature
FREE_BET_EXISTS	409	Free bet already exists

An example of using the assign API method

curl 'https://VELIGAMES_API_URL/reward-api/public/free-bet/assign' \
 --header 'signature: OPERATOR_ID:4asd1CCN...N5CdDx0GCfUspxw==' \
 --header 'Content-Type: application/json' \
 --data '{
     "freeBetId": "33ee9a8112....5653966725a",
     "providerId": "provider1",
     "gameId": "463",
     "playerId": "642ef1f2...3a4a091ef",
     "currency": "EUR",
     "brandId": "someBrandId",
     "endDate": "2024-12-21T12:12:14Z",
     "quantity": "10",
     "config": {
         "betAmount": "50"
     }
 }'

A success response for the assign API method

{ "acknowledged": true }

An example of an error response for the assign API method

{ "error": "BAD_REQUEST", "details": { "brandId": "field is required" } }

API Method: free-bet/assign (VeliSports)

When assigning free bets for the velisports provider, use the same free-bet/assign endpoint with a specific set of parameters. Unlike the standard free bet flow, quantity and endDate are not expected for sports free bets, it is configured in advance in velisports backoffice at the moment. Additionally, the operator can optionally override the template’s claimable setting and claim period by providing claimable and claimPeriod parameters in the request.

Path:

https://VELIGAMES_API_URL/reward-api/public/free-bet/assign

HTTP Method:

POST

Request body

Parameter	Type	Description
freeBetId	string	One-time unique identifier generated by the operator.
providerId	string	Must be velisports.
gameId	string	The unique identifier of the game.
playerId	string	The player’s unique identifier.
currency	string	The player’s currency code.
brandId	string	The identifier of the casino brand.
config	object	Provider-specific configuration. See /free-bet for available options.
providerCampaignId	string	The campaign template identifier on the provider side. Available values can be retrieved via sportsbook/templates.

The following parameters are optional and can be used to override the template’s default settings.

Parameter	Type	Description
claimable	boolean	Override the template’s claimable setting.
claimPeriod	number	Override the template’s claim period (days).

An example of using free-bet/assign for velisports

curl 'https://VELIGAMES_API_URL/reward-api/public/free-bet/assign' \
 --header 'signature: OPERATOR_ID:4asd1CCN...N5CdDx0GCfUspxw==' \
 --header 'Content-Type: application/json' \
 --data '{
     "freeBetId": "33ee9a8112....5653966725a",
     "providerId": "velisports",
     "gameId": "1000",
     "playerId": "642ef1f2...3a4a091ef",
     "currency": "EUR",
     "brandId": "someBrandId",
     "config": {},
     "providerCampaignId": "campaign-abc123",
     "claimable": true,
     "claimPeriod": 7
 }'

Response and errors

The response and error codes are identical to the standard free-bet/assign endpoint.

API Method: sportsbook/templates

The operator makes a request to this endpoint to retrieve the list of available campaign templates from the VeliSports provider. The returned id values are used as the providerCampaignId when assigning a sports free bet.

Path:

https://VELIGAMES_API_URL/reward-api/public/free-bet/sportsbook/templates

HTTP Method:

POST

Request body

The following parameters are required.

Parameter	Type	Description
brandId	string	The identifier of the casino brand.
providerId	string	Must be velisports.
currency	string	The player’s currency code.

The following parameters are optional and can be used to filter and paginate the results.

Parameter	Type	Description
page	number	The page number for pagination. Default is 1.
size	number	The number of items per page. Default is 25.
search	string	A search term to filter templates by name.
fieldNameToOrderBy	string	The field name to sort results by. Default is id.
orderByDescending	boolean	Whether to sort in descending order. Default is true.

An example of using the sportsbook/templates API method

curl 'https://VELIGAMES_API_URL/reward-api/public/free-bet/sportsbook/templates' \
 --header 'signature: OPERATOR_ID:4asd1CCN...N5CdDx0GCfUspxw==' \
 --header 'Content-Type: application/json' \
 --data '{
     "brandId": "someBrandId",
     "providerId": "velisports",
     "currency": "EUR",
     "bonusTypes": ["FREE_BET"],
     "page": 1,
     "size": 25
 }'

JSON Response

Returns a paginated list of available campaign templates.

Parameter	Type	Description
meta	object	Information about the pagination. See the table below for object fields.
items	array	The list of campaign templates. See the table below for object fields.

Meta object fields

Parameter	Type	Description
totalItems	number	The total number of items in the collection that matches the request.
itemCount	number	The number of items returned in this particular response.
itemsPerPage	number	The maximum number of items from the data set that may fit in a page.
totalPages	number	The total number of pages required to deliver the whole collection.
currentPage	number	The current page number for this particular response.

Template object fields

Parameter	Type	Description
id	number	The unique identifier of the template. Used as providerCampaignId when assigning a sports free bet.
name	string	The name of the campaign template.
bonusType	string	The type of the bonus (e.g. FREE_BET, BONUS, INSURANCE, EARLY_PAYOUT).
expirationDate	string	The expiration date of the template (in UTC). Present when validityType is 0.
validForDays	number	The number of days the free bet is valid for after assignment. Present when validityType is 1.
claimable	boolean	Whether the free bet must be claimed by the player before it becomes active.
claimPeriod	number	The number of days the player has to claim the free bet. Present when claimable is true.

A success response for the sportsbook/templates API method

{
    "items": [
        {
            "id": 2757,
            "name": "Veligames Template 1",
            "bonusType": "FREE_BET",
            "expirationDate": "2026-03-30T20:00:00Z",
            "validForDays": null,
            "claimable": false,
            "claimPeriod": null,
        }
    ],
    "meta": {
        "totalItems": 42,
        "itemCount": 1,
        "itemsPerPage": 25,
        "totalPages": 2,
        "currentPage": 1
    }
}

Error Types

Error type	HTTP code	Description
UNKNOWN_ERROR	500	A generic error or an internal server error that can be retried
BAD_REQUEST	400	The parameters are either missing or invalid.
UNAUTHORIZED	401	Invalid signature.

API Method: sportsbook/claim

The operator makes a request to this endpoint to claim an assigned sports free bet on behalf of a player. This is relevant for free bets where the claimable flag is set to true either in the campaign template or overridden in the assign request.

Path:

https://VELIGAMES_API_URL/reward-api/public/free-bet/sportsbook/claim

HTTP Method:

POST

Request body

Parameter	Type	Description
freeBetId	string	The unique identifier of the free bet to claim.
brandId	string	The identifier of the casino brand.

An example of using the sportsbook/claim API method

curl 'https://VELIGAMES_API_URL/reward-api/public/free-bet/sportsbook/claim' \
 --header 'signature: OPERATOR_ID:4asd1CCN...N5CdDx0GCfUspxw==' \
 --header 'Content-Type: application/json' \
 --data '{
     "freeBetId": "33ee9a8112....5653966725a",
     "brandId": "someBrandId"
 }'

Successful response

Parameter	Type	Description
freeBetId	string	The unique identifier of the claimed free bet.
operationType	string	The operation type. Always CLAIM.
status	string	The status of the claim operation. CLAIMED on success.
reason	string	Additional information in case the status is set to ERROR. Otherwise, this parameter is not included.

A success response for the sportsbook/claim API method

{
    "freeBetId": "33ee9a8112....5653966725a",
    "operationType": "CLAIM",
    "status": "CLAIMED"
}

Error Types

Error type	HTTP code	Description
UNKNOWN_ERROR	500	A generic error or an internal server error that can be retried
BAD_REQUEST	400	The parameters are either missing or invalid.
UNAUTHORIZED	401	Invalid signature.
FREE_BET_NOT_FOUND	404	The free bet was not found.

API Method: free-bet/cancel

By sending a request to this endpoint, you cancel an existing free bet.

Path:

https://VELIGAMES_API_URL/reward-api/public/free-bet/cancel

HTTP Method:

POST

Request body

Parameter	Type	Description
freeBetId	string	Unique identifier generated by OPERATOR on /assign that should be cancelled.
brandId	string	The identifier of the casino brand

JSON Response

Parameter	Type	Purpose
acknowledged	boolean	Cancel request is added to the queue and will callback cancellation status to operator.

Error response

VeliGames makes an asynchronous request to the provider to cancel the assigned free bets. According to the applied pre-provider validation protocol, a successful response does not guarantee that you will not get an error status response.

Parameter	Type	Purpose
error	enum	See error types below.
details	object [fieldName]: ‘error description’	Optional description

Error Types

Error type	Status code	Description
UNKNOWN_ERROR	500	A generic error or an internal server error that can be retried
BAD_REQUEST	400	The parameters are either missing or invalid
UNAUTHORIZED	401	Invalid signature
FREE_BET_NOT_FOUND	404	Free bet not found (Cancel/Info)
NOT_ALLOWED	405	Indicates that the requested operation is not allowed, such as canceling a free bet in the STARTED status.

An example of using the cancel API method

curl 'https://VELIGAMES_API_URL/reward-api/public/free-bet/cancel' \
 --header 'signature: OPERATOR_ID:4asd1CCN...N5CdDx0GCfUspxw==' \
 --header 'Content-Type: application/json' \
 --data '{
     "freeBetId": "33ee9a8112....5653966725a",
     "brandId": "someBrandId"
 }'

A success response for the cancel API method

{ "acknowledged": true }

An example of an error response for the cancel API method

{ "error": "BAD_REQUEST", "details": { "brandId": "field is required" } }

API Method: free-bet/info

A request to the this endpoint returns basic information and the current status of an existing free bet.

Path:

https://VELIGAMES_API_URL/reward-api/public/free-bet/info

HTTP Method:

POST

Request body

Parameter	Type	Description
freeBetId	string	Unique identifier generated by OPERATOR on /assign.
brandId	string	The identifier of the casino brand

JSON Response

The JSON response to the /free-bet/info request contains the essential information about the requested free bet. All parameters are of the string type.

Parameter	Type	Purpose
freeBetId	string	The unique identifier of the requested free bet
brandId	string	The identifier of the casino brand
status	enum	The current status of the requested free bet: CREATED ASSIGNED CANCELLED STARTED PLAYED ERROR
reason	string (optional)	More information in case the free bet status is set to ERROR.

Event: status

The free bet status endpoint should be implemented of operator side. This webhook is called by VeliGames to notify operator about the current status of a free bet. Initiated after processing /assign or /cancel

Path:

https://{operator-defined-freebet-status-url}/status

HTTP Method:

POST

Request body

The JSON document in the body of the request contains information about a free bet along with the operation that must be run on the operator’s system

Parameter	Type	Description
freeBetId	string	One-time unique identifier
brandId	string	The unique identifier of the casino brand
operationType	enum	Either ASSIGN or CANCEL
status	string	One of ASSIGNED, CANCELLED, or ERROR
reason	string	Relevant if the status is set to ERROR. Otherwise, this parameter is not be included.

Response

The operator’s system returns the HTTP code 200 indicating the success. In case of error HTTP code or timeout, VeliGames will retry the request several times.

Error response

If the request fails, the operator’s system can return one of the predefined error codes.

Error type	HTTP Status code	Description
UNKNOWN_ERROR	500	A generic error or an internal server error that can be retried
BAD_REQUEST	400	The parameters are either missing or invalid
UNAUTHORIZED	401	Invalid signature
FREE_BET_NOT_FOUND	404	Free bet not found (Cancel/Info)

An example of an error response for the status API method

{ "error": "FREE_BET_NOT_FOUND" }