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.

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.

Additional Fields for FreeBets¶

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

Field	Type	Required	Description
`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 (3 characters, e.g. `EUR`, `USD`).
`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.

Example Request (FreeBets)¶

{
  "rewardType": "FreeBets",
  "name": "Free Spins Reward",
  "description": "10 free spins on Plinko",
  "operatorReference": "OP-REWARD-001",
  "products": ["plinko-8-lines"],
  "startTimeUtc": "2026-06-01T00:00:00Z",
  "endTimeUtc": "2026-06-30T23:59:59Z",
  "createdBy": "[email protected]",
  "betValue": 0.50,
  "betCount": 10,
  "currencyIsoCode": "EUR",
  "creditWalletType": "FreeBet",
  "stakeNotReturned": true
}

Example Response (FreeBets)¶

{
  "message": "OK",
  "data": {
    "rewardType": "FreeBets",
    "id": "rwd-001",
    "operatorId": 1,
    "campaignId": "abc123",
    "name": "Free Spins Reward",
    "description": "10 free spins on Plinko",
    "operatorReference": "OP-REWARD-001",
    "campaignOperatorReference": "OP-SUMMER-2026",
    "products": ["plinko-8-lines"],
    "startTimeUtc": "2026-06-01T00:00:00Z",
    "endTimeUtc": "2026-06-30T23:59:59Z",
    "status": "Scheduled",
    "createdAtUtc": "2026-03-20T12:00:00Z",
    "createdBy": "[email protected]",
    "updatedAtUtc": null,
    "updatedBy": null,
    "cancelledAtUtc": null,
    "cancelledBy": null,
    "betValue": 0.50,
    "betCount": 10,
    "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.
FreeBets-specific: - betValue must be greater than zero. - betCount must be greater than zero. - currencyIsoCode must be exactly 3 characters.

Product Name Resolution

Product names in the products array are resolved to internal product IDs during creation. If a product name is not found for the authenticated operator, the request will fail with a validation error. Contact the Gamnify team to confirm your available product names.

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 Spins Reward",
      "description": "10 free spins on Plinko",
      "operatorReference": "OP-REWARD-001",
      "campaignOperatorReference": "OP-SUMMER-2026",
      "products": ["plinko-8-lines"],
      "startTimeUtc": "2026-06-01T00:00:00Z",
      "endTimeUtc": "2026-06-30T23:59:59Z",
      "status": "Active",
      "createdAtUtc": "2026-03-20T12:00:00Z",
      "createdBy": "[email protected]",
      "updatedAtUtc": null,
      "updatedBy": null,
      "cancelledAtUtc": null,
      "cancelledBy": null,
      "betValue": 0.50,
      "betCount": 10,
      "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.
`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
`betValue`	decimal	The value of each free bet.
`betCount`	integer	The total number of free bets per enrolled player.
`currencyIsoCode`	string	The ISO 4217 currency code.
`creditWalletType`	string	The wallet type being credited (`Real`, `Bonus`, or `FreeBet`).
`stakeNotReturned`	boolean	Whether the stake is withheld on winning free bets.