Reward Enrollments¶

Enrollments link specific players to rewards. Once a player is enrolled, they can consume the reward (e.g. use their free bets) within the configured time window and on the specified products.

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

Enroll Player¶

Enrolls a single player in a reward.

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

Path Parameters¶

Request Headers¶

Request Body¶

Enrollment Overrides¶

The overrides object is polymorphic: the rewardType discriminator determines the concrete shape, mirroring the reward model. When rewardType is FreeBets:

Example Request¶

{
  "operatorPlayerId": "player-123",
  "overrides": {
    "rewardType": "FreeBets",
    "betValue": 2.50,
    "betCount": 8,
    "currencyIsoCode": "EUR"
  }
}

Example Response (FreeBets Enrollment)¶

{
  "message": "OK",
  "data": {
    "rewardType": "FreeBets",
    "id": "enr-001",
    "operatorId": 1,
    "rewardId": "rwd-001",
    "campaignId": "abc123",
    "campaignOperatorReference": "OP-SUMMER-2026",
    "rewardOperatorReference": "OP-REWARD-001",
    "operatorPlayerId": "player-123",
    "products": ["Plinko"],
    "status": "New",
    "startTimeUtc": "2026-06-01T00:00:00Z",
    "endTimeUtc": "2026-06-30T23:59:59Z",
    "createdAtUtc": "2026-03-20T12:00:00Z",
    "updatedAtUtc": null,
    "cancelledAtUtc": null,
    "betValue": 2.50,
    "currencyIsoCode": "EUR",
    "totalBetCount": 8,
    "remainingBetCount": 8,
    "creditWalletType": "FreeBet",
    "stakeNotReturned": true
  },
  "responseCode": "OK"
}

Validation Rules¶

• operatorPlayerId is required and cannot be empty or whitespace. Player IDs are trimmed.
• overrides, when provided, must be allowed by the reward, match the reward's type, and its values must fall within the reward's configured bounds.
• currencyIsoCode in overrides must be a valid supported ISO currency code.

Bulk Enroll Players¶

Enqueues multiple players for enrollment in a reward in a single request.

Endpoint: POST /v1/rewards/{rewardId}/enrollments/bulk

Path Parameters¶

Request Headers¶

Request Body¶

Each entry in players:

Example Request¶

{
  "players": [
    { "operatorPlayerId": "player-123" },
    {
      "operatorPlayerId": "player-456",
      "overrides": {
        "rewardType": "FreeBets",
        "betValue": 5.00,
        "betCount": 10,
        "currencyIsoCode": "EUR"
      }
    },
    { "operatorPlayerId": "player-789" }
  ]
}

Example Response¶

{
  "message": "",
  "data": {
    "jobId": "681f0d3d0c2f0b1c6e27e6cb"
  },
  "responseCode": "OK"
}

Response Behavior¶

• This endpoint returns 202 Accepted.
• The Location header points to the job status endpoint.
• Use Get Bulk Enrollment Job Status to track processing progress and rejection details.

Validation Rules¶

• players must contain between 1 and 1,000 entries.
• Each entry must have a non-empty operatorPlayerId. Player IDs are trimmed.
• Duplicate operatorPlayerId values are rejected.
• Overrides are validated per entry with the same rules as single enrollment. Validation errors identify the offending entry by index (e.g. Players[1]: Bet value must be between 1 and 10.).

Get Bulk Enrollment Job Status¶

Retrieves the current status of a bulk enrollment job.

Endpoint: GET /v1/enrollments/bulk-jobs/{jobId}

Path Parameters¶

Request Headers¶

Example Response¶

{
  "message": "OK",
  "data": {
    "id": "681f0d3d0c2f0b1c6e27e6cb",
    "operatorId": 1,
    "rewardId": "rwd-001",
    "status": "Completed",
    "source": "OperatorApi",
    "sourceReference": null,
    "bulkId": "api:2c77d9fef2b84085b5f70c2c8b5f7b89",
    "createdAtUtc": "2026-03-20T12:00:00Z",
    "startedAtUtc": "2026-03-20T12:00:01Z",
    "completedAtUtc": "2026-03-20T12:00:05Z",
    "acceptedCount": 2,
    "rejectedCount": 1,
    "rejections": [
      {
        "operatorPlayerId": "player-789",
        "reasonCode": "AlreadyEnrolled",
        "reason": "The player is already enrolled in this reward."
      }
    ],
    "attempts": 1,
    "lastErrorCode": null,
    "lastErrorDescription": null,
    "scheduledTriggerContext": null
  },
  "responseCode": "OK"
}

Job Status Values¶

Job Source Values¶

The source field records how the job was created:

scheduledTriggerContext Fields¶

Populated only when source is ScheduledTrigger; null otherwise. Scheduled triggers enroll players in batches, so a single trigger execution can produce multiple bulk jobs.

List Bulk Enrollment Jobs for a Reward¶

Retrieves bulk enrollment jobs for a specific reward with pagination support, ordered newest first.

Endpoint: GET /v1/rewards/{rewardId}/enrollments/bulk-jobs

Path Parameters¶

Query Parameters¶

Request Headers¶

Example Request¶

GET /v1/rewards/rwd-001/enrollments/bulk-jobs?page=1&pageSize=50&status=Completed

Example Response¶

{
  "message": "OK",
  "data": {
    "items": [
      {
        "id": "681f0d3d0c2f0b1c6e27e6cb",
        "operatorId": 1,
        "rewardId": "rwd-001",
        "status": "Completed",
        "source": "OperatorApi",
        "sourceReference": null,
        "bulkId": "api:2c77d9fef2b84085b5f70c2c8b5f7b89",
        "createdAtUtc": "2026-03-20T12:00:00Z",
        "startedAtUtc": "2026-03-20T12:00:01Z",
        "completedAtUtc": "2026-03-20T12:00:05Z",
        "acceptedCount": 2,
        "rejectedCount": 1,
        "attempts": 1,
        "lastErrorCode": null,
        "lastErrorDescription": null,
        "scheduledTriggerContext": null
      }
    ],
    "page": 1,
    "pageSize": 50,
    "totalCount": 1
  },
  "responseCode": "OK"
}

Response Fields¶

Validation Rules¶

• page must be greater than or equal to 1.
• pageSize must be between 1 and 500.
• status, when provided, must be a valid job status value.

List Bulk Enrollment Jobs by Source¶

Retrieves bulk enrollment jobs by their source and source reference with pagination support, ordered newest first.

Endpoint: GET /v1/enrollments/bulk-jobs

Query Parameters¶

Request Headers¶

Example Request¶

GET /v1/enrollments/bulk-jobs?source=BackofficeCsv&sourceReference=upload-2026-03-20&page=1&pageSize=50

Response¶

Returns the same paginated object as List Bulk Enrollment Jobs for a Reward.

Validation Rules¶

• source and sourceReference are required and cannot be empty or whitespace.
• page must be greater than or equal to 1.
• pageSize must be between 1 and 500.

List Bulk Enrollment Jobs for a Trigger Execution¶

Retrieves the bulk enrollment jobs created by a specific scheduled trigger execution, with pagination support, ordered newest first. A single execution can produce multiple jobs because players are enrolled in batches.

The triggerId and executionId values correspond to the scheduledTriggerContext fields on job responses. See Reward Campaign Triggers for how scheduled triggers work.

Endpoint: GET /v1/rewards/triggers/{triggerId}/executions/{executionId}/bulk-jobs

Path Parameters¶

Query Parameters¶

Request Headers¶

Example Response¶

{
  "message": "OK",
  "data": {
    "items": [
      {
        "id": "681f0d3d0c2f0b1c6e27e6cc",
        "operatorId": 1,
        "rewardId": "rwd-001",
        "status": "Completed",
        "source": "ScheduledTrigger",
        "sourceReference": "trg-100:3:exec-7:1",
        "bulkId": "trigger:trg-100:exec:exec-7:iter:3:page:1:reward:rwd-001:shape:standard:chunk:0",
        "createdAtUtc": "2026-03-21T00:00:00Z",
        "startedAtUtc": "2026-03-21T00:00:01Z",
        "completedAtUtc": "2026-03-21T00:00:04Z",
        "acceptedCount": 500,
        "rejectedCount": 0,
        "attempts": 1,
        "lastErrorCode": null,
        "lastErrorDescription": null,
        "scheduledTriggerContext": {
          "triggerId": "trg-100",
          "executionId": "exec-7",
          "iteration": 3,
          "pageNumber": 1,
          "chunkKey": "reward:rwd-001:shape:standard:chunk:0"
        }
      }
    ],
    "page": 1,
    "pageSize": 50,
    "totalCount": 1
  },
  "responseCode": "OK"
}

Validation Rules¶

• page must be greater than or equal to 1.
• pageSize must be between 1 and 500.
• status, when provided, must be a valid job status value.

Get Enrollments for Reward¶

Retrieves enrollments for a specific reward with pagination support.

Endpoint: GET /v1/rewards/{rewardId}/enrollments

Path Parameters¶

Query Parameters¶

Request Headers¶

Example Request¶

GET /v1/rewards/rwd-001/enrollments?page=1&pageSize=50

Response¶

Returns an array of enrollment objects in the data field, ordered by startTimeUtc descending (most recent first). The paging information sits alongside data at the top level of the envelope:

{
  "message": "OK",
  "data": [
    {
      "rewardType": "FreeBets",
      "id": "enr-001",
      "operatorId": 1,
      "rewardId": "rwd-001",
      "campaignId": "abc123",
      "campaignOperatorReference": "OP-SUMMER-2026",
      "rewardOperatorReference": "OP-REWARD-001",
      "operatorPlayerId": "player-123",
      "products": ["Plinko"],
      "status": "Active",
      "startTimeUtc": "2026-06-01T00:00:00Z",
      "endTimeUtc": "2026-06-30T23:59:59Z",
      "createdAtUtc": "2026-03-20T12:00:00Z",
      "updatedAtUtc": null,
      "cancelledAtUtc": null,
      "betValue": 0.50,
      "currencyIsoCode": "EUR",
      "totalBetCount": 10,
      "remainingBetCount": 10,
      "creditWalletType": "FreeBet",
      "stakeNotReturned": true
    }
  ],
  "responseCode": "OK",
  "page": 1,
  "pageSize": 50,
  "totalCount": 137
}

Validation Rules¶

• page must be greater than or equal to 1.
• pageSize must be between 1 and 500.

Search Enrollments¶

Searches a player's enrollments across all rewards, optionally narrowed to a campaign or a reward, with pagination support.

Endpoint: GET /v1/enrollments

Query Parameters¶

Request Headers¶

Example Request¶

GET /v1/enrollments?operatorPlayerId=player-123&campaignId=abc123&page=1&pageSize=50

Response¶

Returns the same paged envelope as Get Enrollments for Reward: enrollment objects in data ordered by startTimeUtc descending, with page, pageSize, and totalCount alongside.

Validation Rules¶

• operatorPlayerId is required and cannot be empty or whitespace.
• campaignId and rewardId, when provided, must be valid Gamnify identifiers. Malformed values are rejected with a validation error.
• page must be greater than or equal to 1.
• pageSize must be between 1 and 500.

Cancel Enrollment¶

Cancels a specific reward enrollment.

Endpoint: POST /v1/enrollments/{enrollmentId}/cancel

Path Parameters¶

Request Headers¶

Example Response¶

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

Enrollment Response Fields¶

Base Fields (All Enrollment Types)¶

Additional Fields for FreeBets Enrollments¶

Typical Integration Flow¶

The following diagram illustrates a typical flow for setting up and managing reward enrollments:

sequenceDiagram
    participant Operator
    participant Gamnify as Gamnify API

    Operator->>+Gamnify: POST /v1/campaigns (Create Campaign)
    Gamnify-->>-Operator: Campaign created (status: Scheduled)

    Operator->>+Gamnify: POST /v1/campaigns/{id}/rewards (Create Reward)
    Gamnify-->>-Operator: Reward created (status: Scheduled)

    Operator->>+Gamnify: POST /v1/rewards/{id}/enrollments/bulk (Enroll Players)
    Gamnify-->>-Operator: 202 Accepted + jobId

    Operator->>+Gamnify: GET /v1/enrollments/bulk-jobs/{jobId}
    Gamnify-->>-Operator: Job status (Pending/Processing/Completed/Failed)

    Note over Operator,Gamnify: Campaign start time reached

    Note over Gamnify: Enrollments transition to Active
    Note over Gamnify: Players can now use their free bets

    Operator->>+Gamnify: GET /v1/rewards/{id}/enrollments (Check Progress)
    Gamnify-->>-Operator: Enrollment statuses (Active/Claimed/Expired)