Rewards¶

Rewards define what enrolled players will receive. Each reward belongs to a campaign and is linked to one or more products (games). The API uses a polymorphic model where the rewardType discriminator determines the concrete type.

For authentication details and general response format, see the Overview.

Reward Types¶

Type	`rewardType` Value	Description
Free Bets	`FreeBets`	Awards the player a configurable number of free bets with a specified value and currency.

Additional reward types may be introduced in the future using the same polymorphic model.

Free Bet Detail Types¶

When rewardType is FreeBets, the freeBetDetails.freeBetDetailsType discriminator determines the concrete Free Bets configuration.

Type	`freeBetDetailsType` Value	Description
Fixed	`Fixed`	Every enrolled player receives the same bet value and bet count.
Ranged	`Ranged`	The reward defines a minimum and maximum range for bet value and bet count.

Create Reward¶

Creates a new reward within an existing campaign. The reward inherits the operator association from the campaign.

Endpoint: POST /v1/campaigns/{campaignId}/rewards

Path Parameters¶

Parameter	Type	Description
`campaignId`	string	The unique identifier of the parent campaign.

Request Headers¶

Header	Type	Required	Description
`X-AUTH-OPERATOR-ID`	integer	Yes	The operator ID.
`X-AUTH-REQUEST-HASH`	string	Yes	The computed SHA-256 authentication hash.
`Content-Type`	string	Yes	Must be `application/json`.

Request Body (Base Fields)¶

All reward creation requests share these base fields:

Field	Type	Required	Description
`rewardType`	string	Yes	The discriminator that determines the reward type. See Reward Types.
`name`	string	Yes	Human-readable name for the reward.
`description`	string	No	Optional description of the reward.
`operatorReference`	string	No	Operator-defined reference identifier for correlation with external systems.
`products`	string[]	Yes	Array of product names (game identifiers) this reward applies to. Must contain at least one entry.
`startTimeUtc`	string (date-time)	Yes	Reward start time in UTC (ISO 8601 format).
`endTimeUtc`	string (date-time)	Yes	Reward end time in UTC. Must be after `startTimeUtc`.
`createdBy`	string	Yes	Identifier of who is creating this reward.
`enrollmentDurationStrategy`	string	No	Enrollment duration mode. Supported values: `InheritFromReward` and `RollingDuration`. Defaults to `InheritFromReward`.
`rollingDuration`	string (duration)	No	Required when `enrollmentDurationStrategy` is `RollingDuration`. Duration value is serialized as a .NET `TimeSpan` string.

Additional Fields for FreeBets¶

When rewardType is FreeBets, the following additional fields are required:

Field	Type	Required	Description
`freeBetDetails`	object	Yes	Polymorphic Free Bets configuration object. See the fixed and ranged structures below.
`creditWalletType`	string	Yes	The wallet type to credit. Possible values: `Real`, `Bonus`, `FreeBet`.
`stakeNotReturned`	boolean	Yes	When `true`, the stake amount is not returned to the player on a winning free bet - only the winnings are credited. When `false`, both the stake and winnings are credited.

`freeBetDetails` for Fixed Free Bets¶

Field	Type	Required	Description
`freeBetDetailsType`	string	Yes	Must be `Fixed`.
`betValue`	decimal	Yes	The value of each free bet. Must be greater than zero.
`betCount`	integer	Yes	The number of free bets awarded to each enrolled player. Must be greater than zero.
`currencyIsoCode`	string	Yes	The ISO 4217 currency code. Currency matching is case-insensitive and normalized to uppercase in responses.

`freeBetDetails` for Ranged Free Bets¶

Field	Type	Required	Description
`freeBetDetailsType`	string	Yes	Must be `Ranged`.
`minBetValue`	decimal	Yes	Minimum allowed bet value. Must be greater than zero.
`maxBetValue`	decimal	Yes	Maximum allowed bet value. Must be greater than or equal to `minBetValue`.
`minBetCount`	integer	Yes	Minimum allowed bet count. Must be greater than zero.
`maxBetCount`	integer	Yes	Maximum allowed bet count. Must be greater than or equal to `minBetCount`.
`currencyIsoCode`	string	Yes	The ISO 4217 currency code.

Example Request (FreeBets)¶

{
  "rewardType": "FreeBets",
  "name": "Free Bets Reward",
  "description": "Fixed free bets on Plinko",
  "operatorReference": "OP-REWARD-001",
  "products": ["Plinko", "Mines"],
  "startTimeUtc": "2026-06-01T00:00:00Z",
  "endTimeUtc": "2026-06-30T23:59:59Z",
  "createdBy": "[email protected]",
  "freeBetDetails": {
    "freeBetDetailsType": "Fixed",
    "betValue": 1.50,
    "betCount": 5,
    "currencyIsoCode": "EUR"
  },
  "creditWalletType": "FreeBet",
  "stakeNotReturned": true
}

Example Response (FreeBets)¶

{
  "message": "OK",
  "data": {
    "rewardType": "FreeBets",
    "id": "rwd-001",
    "operatorId": 1,
    "campaignId": "abc123",
    "name": "Free Bets Reward",
    "description": "Fixed free bets on Plinko",
    "operatorReference": "OP-REWARD-001",
    "campaignOperatorReference": "OP-SUMMER-2026",
    "products": ["Plinko", "Mines"],
    "startTimeUtc": "2026-06-01T00:00:00Z",
    "endTimeUtc": "2026-06-30T23:59:59Z",
    "enrollmentDurationStrategy": "InheritFromReward",
    "rollingDuration": null,
    "status": "Scheduled",
    "createdAtUtc": "2026-03-20T12:00:00Z",
    "createdBy": "[email protected]",
    "updatedAtUtc": null,
    "updatedBy": null,
    "cancelledAtUtc": null,
    "cancelledBy": null,
    "freeBetDetails": {
      "freeBetDetailsType": "Fixed",
      "betValue": 1.50,
      "betCount": 5,
      "currencyIsoCode": "EUR"
    },
    "creditWalletType": "FreeBet",
    "stakeNotReturned": true
  },
  "responseCode": "OK"
}

Validation Rules¶

name is required and cannot be empty or whitespace.
createdBy is required and cannot be empty or whitespace.
endTimeUtc must be strictly after startTimeUtc.
products must contain at least one product name.
Product names are validated against the operator's configured products. An error is returned if a product is not found.
Reward products are also checked against the operator's reward-enabled product configuration. If rewards are disabled for the operator, or a requested product is not allowed for rewards, the request fails.
enrollmentDurationStrategy can be InheritFromReward or RollingDuration.
When enrollmentDurationStrategy is RollingDuration, rollingDuration must be greater than zero.
FreeBets-specific: - currencyIsoCode must be a valid supported ISO currency code. - The operator must be configured to allow the requested wallet currency. - Fixed free bets require positive betValue and betCount. - Ranged free bets require positive minimum values, and each maximum must be greater than or equal to its corresponding minimum.

Product Name Resolution

Product names in the products array are resolved to internal product IDs during creation. The service currently resolves names from both legacy and newer product configuration sources. If a product name is not found for the authenticated operator, the request will fail. Contact the Gamnify team to confirm your available product names.

Operator Settings Affect Validation

Reward creation is validated against operator configuration. In practice, this means the operator must have rewards enabled for the requested products, and the wallet currency used by the reward must be allowed for that operator.

Get All Rewards¶

Retrieves all rewards for the authenticated operator across all campaigns.

Endpoint: GET /v1/rewards

Request Headers¶

Header	Type	Required	Description
`X-AUTH-OPERATOR-ID`	integer	Yes	The operator ID.
`X-AUTH-REQUEST-HASH`	string	Yes	The computed SHA-256 authentication hash.

Example Response¶

{
  "message": "OK",
  "data": [
    {
      "rewardType": "FreeBets",
      "id": "rwd-001",
      "operatorId": 1,
      "campaignId": "abc123",
       "name": "Free Bets Reward",
       "description": "Fixed free bets on Plinko",
       "operatorReference": "OP-REWARD-001",
       "campaignOperatorReference": "OP-SUMMER-2026",
       "products": ["Plinko", "Mines"],
       "startTimeUtc": "2026-06-01T00:00:00Z",
       "endTimeUtc": "2026-06-30T23:59:59Z",
       "enrollmentDurationStrategy": "InheritFromReward",
       "rollingDuration": null,
       "status": "Active",
      "createdAtUtc": "2026-03-20T12:00:00Z",
      "createdBy": "[email protected]",
      "updatedAtUtc": null,
      "updatedBy": null,
      "cancelledAtUtc": null,
      "cancelledBy": null,
       "freeBetDetails": {
         "freeBetDetailsType": "Fixed",
         "betValue": 1.50,
         "betCount": 5,
         "currencyIsoCode": "EUR"
       },
       "creditWalletType": "FreeBet",
       "stakeNotReturned": true
    }
  ],
  "responseCode": "OK"
}

Get Rewards in Campaign¶

Retrieves all rewards within a specific campaign.

Endpoint: GET /v1/campaigns/{campaignId}/rewards

Path Parameters¶

Parameter	Type	Description
`campaignId`	string	The unique identifier of the campaign.

Request Headers¶

Header	Type	Required	Description
`X-AUTH-OPERATOR-ID`	integer	Yes	The operator ID.
`X-AUTH-REQUEST-HASH`	string	Yes	The computed SHA-256 authentication hash.

Response¶

Returns an array of reward objects in the data field (same structure as Get All Rewards).

Get Reward by ID¶

Retrieves a specific reward by its ID.

Endpoint: GET /v1/rewards/{rewardId}

Path Parameters¶

Parameter	Type	Description
`rewardId`	string	The unique identifier of the reward.

Request Headers¶

Header	Type	Required	Description
`X-AUTH-OPERATOR-ID`	integer	Yes	The operator ID.
`X-AUTH-REQUEST-HASH`	string	Yes	The computed SHA-256 authentication hash.

Response¶

Returns a single reward object in the data field.

Cancel Reward¶

Cancels a reward. This will prevent any further use of this reward by enrolled players.

Endpoint: POST /v1/rewards/{rewardId}/cancel

Path Parameters¶

Parameter	Type	Description
`rewardId`	string	The unique identifier of the reward to cancel.

Request Headers¶

Header	Type	Required	Description
`X-AUTH-OPERATOR-ID`	integer	Yes	The operator ID.
`X-AUTH-REQUEST-HASH`	string	Yes	The computed SHA-256 authentication hash.
`Content-Type`	string	Yes	Must be `application/json`.

Request Body¶

Field	Type	Required	Description
`cancelledBy`	string	Yes	Identifier of who is cancelling this reward.

Example Request¶

{
  "cancelledBy": "[email protected]"
}

Example Response¶

{
  "message": "OK",
  "data": {},
  "responseCode": "OK"
}

Validation Rules¶

cancelledBy is required and cannot be empty or whitespace.

Reward Response Fields¶

Base Fields (All Reward Types)¶

Field	Type	Description
`rewardType`	string	The reward type discriminator (e.g. `FreeBets`).
`id`	string	Unique reward identifier assigned by Gamnify.
`operatorId`	integer	The operator this reward belongs to.
`campaignId`	string	The parent campaign identifier.
`name`	string	Human-readable reward name.
`description`	string (nullable)	Reward description.
`operatorReference`	string (nullable)	Operator-defined reference identifier.
`campaignOperatorReference`	string (nullable)	The operator reference from the parent campaign.
`products`	string[]	Product names this reward applies to.
`startTimeUtc`	string (date-time)	Reward start time in UTC.
`endTimeUtc`	string (date-time)	Reward end time in UTC.
`enrollmentDurationStrategy`	string	Enrollment duration mode: `InheritFromReward` or `RollingDuration`.
`rollingDuration`	string (duration, nullable)	Rolling enrollment duration when `enrollmentDurationStrategy` is `RollingDuration`.
`status`	string	Current status: `Scheduled`, `Active`, `Ended`, or `Cancelled`. See Status Lifecycles.
`createdAtUtc`	string (date-time)	Timestamp when the reward was created.
`createdBy`	string	Who created the reward.
`updatedAtUtc`	string (date-time, nullable)	Timestamp of the last update, if any.
`updatedBy`	string (nullable)	Who last updated the reward, if applicable.
`cancelledAtUtc`	string (date-time, nullable)	Timestamp when the reward was cancelled, if applicable.
`cancelledBy`	string (nullable)	Who cancelled the reward, if applicable.

Additional Fields for FreeBets¶

Field	Type	Description
`freeBetDetails`	object	The concrete Free Bets payload. See the `Fixed` and `Ranged` variants above.
`creditWalletType`	string	The wallet type being credited (`Real`, `Bonus`, or `FreeBet`).
`stakeNotReturned`	boolean	Whether the stake is withheld on winning free bets.

Rewards¶

Reward Types¶

Free Bet Detail Types¶

Create Reward¶

Path Parameters¶

Request Headers¶

Request Body (Base Fields)¶

Additional Fields for FreeBets¶

freeBetDetails for Fixed Free Bets¶

freeBetDetails for Ranged Free Bets¶

Example Request (FreeBets)¶

Example Response (FreeBets)¶

Validation Rules¶

Get All Rewards¶

Request Headers¶

Example Response¶

Get Rewards in Campaign¶

Path Parameters¶

Request Headers¶

Response¶

Get Reward by ID¶

Path Parameters¶

Request Headers¶

Response¶

Cancel Reward¶

Path Parameters¶

Request Headers¶

Request Body¶

Example Request¶

Example Response¶

Validation Rules¶

Reward Response Fields¶

Base Fields (All Reward Types)¶

Additional Fields for FreeBets¶

`freeBetDetails` for Fixed Free Bets¶

`freeBetDetails` for Ranged Free Bets¶