Backend integration

Bonus API introduction

note

Provider - side which provides games (Aviatrix).

Partner - side which integrates games.

Brand - partner's casino website where users play games and place bets.

This document describes the methods implemented by the provider. These methods are used to retrieve a list of bonus configurations, to manage bonuses and bonus assignments, to retrieve bonus assignment status per player.

good to know

API-generated bonuses follow the same rules as manual bonuses. Any bets made with these bonuses are deducted 100% from the overall turnover.

Bonus API methods

good to know

All POST requests contain the X-Auth-Signature HTTP header required to authenticate the host. This removes the need for IP whitelisting during the integration process. Otherwise, it deprives the provider of the ability to scale quickly (horizontally) without notifying the platform.

tip

Ask your integration manager for the base URL.

/CreateBonusConfig

Method is called to create new bonus configuration.

Attention

When creating a bonus configuration for multiple games in a single request, only games within the same category can be specified: crash games or slot games.

Game combination examples:

• nft-aviatrix
• second-chance
• nft-aviatrix, second-chance
• aviatrix-fruits

Example of the request

Attention

Request headers specified in example are required: Accept, Content-Type, X-Auth-Signature.

POST /bonus/v1/CreateBonusConfig HTTP/1.1
Content-Type: application/json
Accept: application/json
X-Auth-Signature: <signature>

{
  "cid": "some-brand-id",
  "config": {
    "type": "free_bets",
    "validFrom": "2020-12-03T12:15:30.000Z",
    "validTo": "2020-12-03T12:15:30.000Z",
    "gameSettings": [
      {
      "gameId": "some-game-id",
      "minOddsWagering": 50.0,
      "maxOddsWagering": 150.0
      }
    ],
    "isPlayable": false,
    "wagering": {
      "multiplier": 10,
      "useBonusMoney": true
    }
  }
}

Parameter	Description	Type	Requirements	Explanation
cid	brand identifier	string	required	unique identifier
config.type	bonus configuration type	string	required	available values: free_bets
config.validFrom	the begin of valid bonus configuration period	timestamp	required	format: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339
config.validTo	the end of valid bonus configuration period	timestamp	required	format: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339
config.gameSettings	list of game specific settings	array	required	settings for a specific game type; at the same time, only games within the same category can be specified: crash games or slot games
gameId	game identifier	string	required	identifiers example: nft-aviatrix, second-chance, aviatrix-fruits. To see more identifiers check list of all products page
minOddsWagering	wagering minimum odds	double	optional	odds in minor currency unit format (1.95 -> 195); valid range [0-10000]; not supported by aviatrix-fruits
maxOddsWagering	wagering maximum odds	double	optional	odds in minor currency unit format (1.95 -> 195); valid range [0-10000]; not supported by aviatrix-fruits
config.isPlayable	possibility to play with bonus balance	bool	required	if true then it is possible to play with bonus balance
wagering.multiplier	wagering multiplier	integer	required	integer multiplier for a wagering, for example 30
wagering.useBonusMoney	dependency between bonus balance and wagering	bool	required	if true then playing with bonus balance will affect wagering

Example of the response from the server

HTTP/1.1 200 OK
{
  "bonusConfigId": "6f41bd2a-4621-42e5-883c-647b8995684d",
  "cid": "some-brand-id",
  "config": {
    "type": "free_bets",
    "validFrom": "2020-12-03T12:15:30.000Z",
    "validTo": "2020-12-03T12:15:30.000Z",
    "gameSettings": [
      {
      "gameId": "some-game-id",
      "minOddsWagering": 50.0,
      "maxOddsWagering": 150.0
      }
    ],
    "isPlayable": false,
    "wagering": {
      "multiplier": 10,
      "useBonusMoney": true
    }
  }
}

Parameter	Description	Type	Explanation
bonusConfigId	bonus configuration identifier	string	unique identifier, format: uuid
cid	brand identifier	string	unique identifier
config.type	bonus configuration type	string	available values: free_bets
config.validFrom	the begin of valid bonus configuration period	timestamp	format: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339
config.validTo	the end of valid bonus configuration period	timestamp	format: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339
config.gameSettings	list of game specific settings	array	settings for a specific game type; at the same time, only games within the same category can be specified: crash games or slot games
gameId	game identifier	string	identifiers example: nft-aviatrix, second-chance, aviatrix-fruits. To see more identifiers check list of all products page
minOddsWagering	wagering minimum odds	double	odds in minor currency unit format (1.95 -> 195); valid range [0-10000]; not supported by aviatrix-fruits
maxOddsWagering	wagering maximum odds	double	odds in minor currency unit format (1.95 -> 195); valid range [0-10000]; not supported by aviatrix-fruits
config.isPlayable	possibility to play with bonus balance	bool	if true then it is possible to play with bonus balance
wagering.multiplier	wagering multiplier	integer	integer multiplier for a wagering, for example 30
wagering.useBonusMoney	dependency between bonus balance and wagering	bool	if true then playing with bonus balance will affect wagering

/GetBonusConfigs

Method is called to retrieve list of existing bonus configurations for specified brand.

Example of the request

Attention

Request headers specified in example are required: Accept, Content-Type, X-Auth-Signature.

POST /bonus/v1/GetBonusConfigs HTTP/1.1
Content-Type: application/json
Accept: application/json
X-Auth-Signature: <signature>

{
  "cid": "some-brand-id",
  "showActiveOnly": false
}

Parameter	Description	Type	Requirements	Explanation
cid	brand identifier	string	required	unique identifier
showActiveOnly	filter flag	bool	optional	allows to display only active bonus configurations

Example of the response from the server

HTTP/1.1 200 OK
{
  "values": [
    {
      "bonusConfigId": "6f41bd2a-4621-42e5-883c-647b8995684d",
      "cid": "some-brand-id",
      "config": {
        "type": "free_bets",
        "validFrom": "2020-12-03T12:15:30.000Z",
        "validTo": "2020-12-03T12:15:30.000Z",
        "gameSettings": [
          {
          "gameId": "some-game-id",
          "minOddsWagering": 50.0,
          "maxOddsWagering": 150.0
          }
        ],
        "isPlayable": false,
        "wagering": {
          "multiplier": 10,
          "useBonusMoney": true
        }
      }
    }
  ]
}

Parameter	Description	Type	Explanation
values	list of bonus configurations	array	can present expired, active and inactive configurations
bonusConfigId	bonus configuration identifier	string	unique identifier, format: uuid
cid	brand identifier	string	unique identifier
config.type	bonus configuration type	string	available values: free_bets
config.validFrom	the begin of valid bonus configuration period	timestamp	format: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339
config.validTo	the end of valid bonus configuration period	timestamp	format: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339
config.gameSettings	list of game specific settings	array	settings for a specific game type; at the same time, only games within the same category can be specified: crash games or slot games
gameId	game identifier	string	identifiers example: nft-aviatrix, second-chance, aviatrix-fruits. To see more identifiers check list of all products page
minOddsWagering	wagering minimum odds	double	odds in minor currency unit format (1.95 -> 195); valid range [0-10000]; not supported by aviatrix-fruits
maxOddsWagering	wagering maximum odds	double	odds in minor currency unit format (1.95 -> 195); valid range [0-10000]; not supported by aviatrix-fruits
config.isPlayable	possibility to play with bonus balance	bool	if true then it is possible to play with bonus balance
wagering.multiplier	wagering multiplier	integer	integer multiplier for a wagering, for example 30
wagering.useBonusMoney	dependency between bonus balance and wagering	bool	if true then playing with bonus balance will affect wagering

/CreateFreeBet

Method is called to create new bonus campaign within existing bonus configuration.

Example of the request

Attention

Request headers specified in example are required: Accept, Content-Type, X-Auth-Signature.

POST /bonus/v1/CreateFreeBet HTTP/1.1
Content-Type: application/json
Accept: application/json
X-Auth-Signature: <signature>

{
  "cid": "some-brand-id",
  "bonusConfigId": "6f41bd2a-4621-42e5-883c-647b8995684d",
  "name": "Some Campaign Name",
  "bonus": {
    "betCount": 5,
    "currencySettings": {
      "EUR": {
        "amount": 5,
        "maxPromoWinAmount": 10000,
        "maxBetWageringAmount": 200
      },
      "USD": {
        "amount": 6,
        "maxPromoWinAmount": 12000,
        "maxBetWageringAmount": 400
      }
    },
    "validTo": "2020-12-03T12:15:30.000Z"
  }
}

Parameter	Description	Type	Requirements	Explanation
cid	brand identifier	string	required	unique identifier
bonusConfigId	bonus configuration identifier	string	required	unique identifier, format: uuid
name	bonus campaign name	string	required	naming of a bonus campaign
bonus.betCount	amount of bonus bets	integer	required	bonus bets that will be granted to a player
bonus.currencySettings	map of currency specific settings	map	required	bonus bet currency, format ISO-4217-3
amount	amount of bonus bet	integer	required	format minor currency unit, example: 1.95$ -> 195; can't be lesser than minimal and greater than maximal bet amount for specified brand
maxPromoWinAmount	maximum bonus win amount	integer	required	format minor currency unit, example: 1.95$ -> 195; can't be greater than maximal win amount for specified brand
maxBetWageringAmount	maximum amount for wagering	integer	optional	format minor currency unit, example: 1.95$ -> 195
bonus.validTo	expiration period of bonus campaign	timestamp	required	format: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339

Example of the response from the server

HTTP/1.1 200 OK
{
  "bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e",
  "cid": "some-brand-id",
  "bonusConfigId": "6f41bd2a-4621-42e5-883c-647b8995684d",
  "name": "Some Campaign Name",
  "bonus": {
    "betCount": 5,
    "currencySettings": {
      "EUR": {
        "amount": 5,
        "maxPromoWinAmount": 10000,
        "maxBetWageringAmount": 200
      },
      "USD": {
        "amount": 6,
        "maxPromoWinAmount": 12000,
        "maxBetWageringAmount": 400
      }
    },
    "validTo": "2020-12-03T12:15:30.000Z"
  }
}

Parameter	Description	Type	Explanation
bonusId	bonus campaign identifier	string	bonus campaign unique identifier, format: uuid
cid	brand identifier	string	unique identifier
bonusConfigId	bonus configuration identifier	string	unique identifier, format: uuid
name	bonus campaign name	string	naming of a bonus campaign
bonus.betCount	amount of bonus bets	integer	bonus bets that will be granted to a player
bonus.currencySettings	map of currency specific settings	map	bonus bet currency, format: ISO-4217-3
amount	amount of bonus bet	integer	format minor currency unit, example: 1.95$ -> 195; can't be lesser than minimal and greater than maximal bet amount for specified brand
maxPromoWinAmount	maximum bonus win amount	integer	format minor currency unit, example: 1.95$ -> 195; can't be greater than maximal win amount for specified brand
maxBetWageringAmount	maximum amount for wagering	integer	format minor currency unit, example: 1.95$ -> 195
bonus.validTo	expiration period of bonus campaign	timestamp	format: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339

/DisableBonus

Method is called to disable existing bonus campaign.

Example of the request

Attention

Request headers specified in example are required: Accept, Content-Type, X-Auth-Signature.

POST /bonus/v1/DisableBonus HTTP/1.1
Content-Type: application/json
Accept: application/json
X-Auth-Signature: <signature>

{
  "bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e",
  "cid": "some-brand-id"
}

Parameter	Description	Type	Requirements	Explanation
bonusId	bonus campaign identifier	string	required	bonus campaign unique identifier, format: uuid
cid	brand identifier	string	required	unique identifier

Example of the response from the server

HTTP/1.1 200 OK
{
  "bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e"
}

Parameter	Description	Type	Explanation
bonusId	bonus campaign identifier	string	bonus campaign unique identifier, format: uuid

/AssignBonus

Method is called to assign a bonus to specified players.

Example of the request

Attention

Request headers specified in example are required: Accept, Content-Type, X-Auth-Signature.

POST /bonus/v1/AssignBonus HTTP/1.1
Content-Type: application/json
Accept: application/json
X-Auth-Signature: <signature>

{
  "bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e",
  "playerIds": ["player1", "player2", "player3"],
  "cid": "some-brand-id"
}

Parameter	Description	Type	Requirements	Explanation
bonusId	bonus campaign identifier	string	required	bonus campaign unique identifier, format: uuid
playerIds	list of player identifiers	array of strings	required	players that will be granted with a bonus related to specified bonus campaign
cid	brand identifier	string	required	unique identifier

Example of the response from the server

HTTP/1.1 200 OK
{
  "bonusJobId": "71ac9c1b-faa7-4b77-ba49-beed09f3fb00",
  "bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e",
  "status": "pending",
  "createdAt": "2020-12-03T12:15:30.000Z"
}

Parameter	Description	Type	Explanation
bonusJobId	bonus job identifier	string	unique identifier for a job that will assign/revoke bonus to/from players, format: uuid
bonusId	bonus campaign identifier	string	bonus campaign unique identifier, format: uuid
status	bonus job status	string	possible values: pending, completed, failed
createdAt	start of bonus job process	timestamp	format: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339

/GetAssignBonusStatus

Method is called to retrieve bonus assignment job status.

Example of the request

Attention

Request headers specified in example are required: Accept, Content-Type, X-Auth-Signature.

POST /bonus/v1/GetAssignBonusStatus HTTP/1.1
Content-Type: application/json
Accept: application/json
X-Auth-Signature: <signature>

{
  "jobBonusAssignmentId": "99999",
  "cid": "123"
}

Parameter	Description	Type	Requirements	Explanation
jobBonusAssignmentId	bonus job identifier	string	required	unique identifier for a job that will assign/revoke bonus to/from players, format: uuid
cid	brand identifier	string	required	unique identifier

Example of the response from the server

HTTP/1.1 200 OK
{
  "bonusJobId": "71ac9c1b-faa7-4b77-ba49-beed09f3fb00",
  "bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e",
  "status": "pending",
  "createdAt": "2020-12-03T12:15:30.000Z"
}

Parameter	Description	Type	Explanation
bonusJobId	bonus job identifier	string	unique identifier for a job that will assign/revoke bonus to/from players, format: uuid
bonusId	bonus campaign identifier	string	bonus campaign unique identifier, format: uuid
status	state of bonus job process	string	possible values: pending, completed, failed
createdAt	start of bonus job process	timestamp	format: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339

/RevokeBonus

Method is called to revoke bonus assignment for specific players.

Example of the request

Attention

Request headers specified in example are required: Accept, Content-Type, X-Auth-Signature.

POST /bonus/v1/RevokeBonus HTTP/1.1
Content-Type: application/json
Accept: application/json
X-Auth-Signature: <signature>

{
  "bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e",
  "playerIds": ["player1", "player2", "player3"],
  "cid": "some-brand-id"
}

Parameter	Description	Type	Requirements	Explanation
bonusId	bonus campaign identifier	string	required	bonus campaign unique identifier, format: uuid
playerIds	list of player identifiers	array of strings	required	players whose bonus we want to revoke
cid	brand identifier	string	required	unique identifier

Example of the response from the server

HTTP/1.1 200 OK
{
  "bonusJobId": "71ac9c1b-faa7-4b77-ba49-beed09f3fb00",
  "bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e",
  "status": "pending",
  "createdAt": "2020-12-03T12:15:30.000Z"
}

Parameter	Description	Type	Explanation
bonusJobId	bonus job identifier	string	unique identifier for a job that will assign/revoke bonus to/from players, format: uuid
bonusId	bonus campaign identifier	string	bonus campaign unique identifier, format: uuid
status	state of bonus job process	string	possible values: pending, completed, failed
createdAt	start of bonus job process	timestamp	format: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339

/GetPlayerBonusAssignment

Method is called to retrieve bonus state and wagering progress for specific players.

Example of the request

Attention

Request headers specified in example are required: Accept, Content-Type, X-Auth-Signature.

POST /bonus/v1/GetPlayerBonusAssignment HTTP/1.1
Content-Type: application/json
Accept: application/json
X-Auth-Signature: <signature>

{
  "bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e",
  "playerIds": ["player1", "player2", "player3"],
  "cid": "some-brand-id"
}

Parameter	Description	Type	Requirements	Explanation
bonusId	bonus campaign identifier	string	required	bonus campaign unique identifier, format: uuid
playerIds	list of player identifiers	array of strings	required	players whose bonus state we want to clarify
cid	brand identifier	string	required	unique identifier

Example of the response from the server

HTTP/1.1 200 OK
{
  "assignments": [
    {
      "playerBonusAssignmentId": "71ac9c1b-faa7-4b77-ba49-beed09f3fb00",
      "playerId": "player1",
      "createdAt": "2025-06-11T16:48:55Z",
      "validTo": "2020-12-03T12:15:30.000Z",
      "freeBet": {
        "betCountPlaced": 5,
        "betCountLimit": 10,
        "status": "active"
      }
    }
  ]
}

Parameter	Description	Type	Explanation
assignments	list of player's bonus states	array	list that shows current state of a bonus for players that were passed in request
playerBonusAssignmentId	bonus job identifier	string	unique identifier for a player and bonus relation, format: uuid
playerId	player identifier	string	player identifier in partner's system
createdAt	when bonus was assigned to a player	timestamp	format: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339
validTo	bonus active period	timestamp	format: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339
freeBet.betCountPlaced	amount of played bonus bets	integer	amount of bonus bets that player has made
freeBet.betCountLimit	amount of granted bonus bets	integer	amount of bonus bets granted to a player by bonus campaign
freeBet.status	bonus bet wagering status	string	possible values: preassigned, pending, active, wagering, completed, expired, deassigned, unwagered, canceled

Bonus API error processing

In general case when error occurs then provider's server returns the response in format:

{
  "code": 400,
  "message": "error text"
}

Error response details

HTTP Status	Message text	Retry	Description
400	Bad request: playerIds array exceeds 100 elements	No	The playerIds array must contain no more than 100 elements.
400	Bad request: betCount must be non-negative	No	The betCount value cannot be negative.
400	Bad request: bonus is disabled	No	Attempt to assign disabled bonus.
400	Missing required field	No	One or more required fields are missing.
400	Invalid request	No	General validation error. Please contact provider's support team.
404	Bonus not found	No	The specified bonusId does not exist.
404	Job bonus assignment not found	No	The referenced jobBonusAssignment was not found.
404	Bonus config not found	No	The provided bonusConfigId does not exist.
429	Too many requests	Yes	The client has sent too many requests in a given amount of time. Throttling in effect.
429	Monthly quota reached: create free bet. Contact your integration manager.	Yes	The domain has reached its monthly quota for creating free bet bonus.
429	Monthly quota reached: assign bonus. Contact your integration manager.	Yes	The domain has reached its monthly quota for bonus assignment.
500	Internal server error	Yes	Unexpected server error. If it remains after few retry attempts, then please contact provider's support team.