Rewards Campaigns¶

Campaigns are top-level containers that group rewards under a time-bound promotion. Before creating rewards or enrolling players, you must first create a campaign.

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

Create Campaign¶

Creates a new rewards campaign for the authenticated operator.

Endpoint: POST /v1/campaigns

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
`name`	string	Yes	Human-readable name for the campaign.
`description`	string	No	Optional description of the campaign.
`operatorReference`	string	No	Operator-defined reference identifier for correlation with external systems.
`startTimeUtc`	string (date-time)	Yes	Campaign start time in UTC (ISO 8601 format).
`endTimeUtc`	string (date-time)	Yes	Campaign end time in UTC. Must be after `startTimeUtc`.
`createdBy`	string	Yes	Identifier of who is creating this campaign (e.g. operator user email).

Example Request¶

{
  "name": "Summer Campaign 2026",
  "description": "Summer promotional campaign",
  "operatorReference": "OP-SUMMER-2026",
  "startTimeUtc": "2026-06-01T00:00:00Z",
  "endTimeUtc": "2026-08-31T23:59:59Z",
  "createdBy": "[email protected]"
}

Example Response¶

{
  "message": "OK",
  "data": {
    "id": "abc123",
    "operatorId": 1,
    "name": "Summer Campaign 2026",
    "description": "Summer promotional campaign",
    "operatorReference": "OP-SUMMER-2026",
    "startTimeUtc": "2026-06-01T00:00:00Z",
    "endTimeUtc": "2026-08-31T23:59:59Z",
    "status": "Scheduled",
    "createdAtUtc": "2026-03-20T12:00:00Z",
    "createdBy": "[email protected]",
    "updatedAtUtc": null,
    "updatedBy": null,
    "cancelledAtUtc": null,
    "cancelledBy": null
  },
  "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.

Get All Campaigns¶

Retrieves all rewards campaigns for the authenticated operator.

Endpoint: GET /v1/campaigns

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": [
    {
      "id": "abc123",
      "operatorId": 1,
      "name": "Summer Campaign 2026",
      "description": "Summer promotional campaign",
      "operatorReference": "OP-SUMMER-2026",
      "startTimeUtc": "2026-06-01T00:00:00Z",
      "endTimeUtc": "2026-08-31T23:59:59Z",
      "status": "Active",
      "createdAtUtc": "2026-03-20T12:00:00Z",
      "createdBy": "[email protected]",
      "updatedAtUtc": null,
      "updatedBy": null,
      "cancelledAtUtc": null,
      "cancelledBy": null
    }
  ],
  "responseCode": "OK"
}

Get Campaign by ID¶

Retrieves a specific rewards campaign by its ID.

Endpoint: GET /v1/campaigns/{campaignId}

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.

Example Response¶

{
  "message": "OK",
  "data": {
    "id": "abc123",
    "operatorId": 1,
    "name": "Summer Campaign 2026",
    "description": "Summer promotional campaign",
    "operatorReference": "OP-SUMMER-2026",
    "startTimeUtc": "2026-06-01T00:00:00Z",
    "endTimeUtc": "2026-08-31T23:59:59Z",
    "status": "Active",
    "createdAtUtc": "2026-03-20T12:00:00Z",
    "createdBy": "[email protected]",
    "updatedAtUtc": null,
    "updatedBy": null,
    "cancelledAtUtc": null,
    "cancelledBy": null
  },
  "responseCode": "OK"
}

Cancel Campaign¶

Cancels a rewards campaign. This will prevent any further use of rewards within the campaign.

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

Path Parameters¶

Parameter	Type	Description
`campaignId`	string	The unique identifier of the campaign 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 campaign.

Example Request¶

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

Example Response¶

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

Validation Rules¶

cancelledBy is required and cannot be empty or whitespace.

Campaign Response Fields¶

All campaign endpoints return the following fields in the data property:

Field	Type	Description
`id`	string	Unique campaign identifier assigned by Gamnify.
`operatorId`	integer	The operator this campaign belongs to.
`name`	string	Human-readable campaign name.
`description`	string (nullable)	Campaign description.
`operatorReference`	string (nullable)	Operator-defined reference identifier.
`startTimeUtc`	string (date-time)	Campaign start time in UTC.
`endTimeUtc`	string (date-time)	Campaign end time in UTC.
`status`	string	Current status: `Scheduled`, `Active`, `Ended`, or `Cancelled`. See Status Lifecycles.
`createdAtUtc`	string (date-time)	Timestamp when the campaign was created.
`createdBy`	string	Who created the campaign.
`updatedAtUtc`	string (date-time, nullable)	Timestamp of the last update, if any.
`updatedBy`	string (nullable)	Who last updated the campaign, if applicable.
`cancelledAtUtc`	string (date-time, nullable)	Timestamp when the campaign was cancelled, if applicable.
`cancelledBy`	string (nullable)	Who cancelled the campaign, if applicable.