Generate Codes

POST /v1/campaigns/codes/generate

Generates a batch of unique, redeemable codes for the campaign. Each code awards a fixed number of points when redeemed. Codes are returned in plaintext only once — store them securely.

Authentication

Header	Required	Value
`X-API-Secret`	Yes	Your secret key
`Content-Type`	Yes	`application/json`

Request Body

Field	Type	Required	Description
`slug`	`string`	Yes	Campaign slug (e.g., `summer-promo`)
`batchSize`	`integer`	Yes	Number of codes to generate (1—10,000)
`pointsValue`	`integer`	Yes	Points each code awards when redeemed
`label`	`string`	No	Label for this batch (e.g., “Holiday campaign mailers”)
`expiresAt`	`datetime`	No	ISO 8601 expiration date for the codes

Request Examples

curl -X POST https://api.gamifyhost.com/v1/campaigns/codes/generate \
  -H "X-API-Secret: sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "summer-promo",
    "batchSize": 100,
    "pointsValue": 500,
    "label": "In-store promo cards",
    "expiresAt": "2025-12-31T23:59:59Z"
  }'

const response = await fetch(
  'https://api.gamifyhost.com/v1/campaigns/codes/generate',
  {
    method: 'POST',
    headers: {
      'X-API-Secret': 'sk_live_your_secret_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      slug: 'summer-promo',
      batchSize: 100,
      pointsValue: 500,
      label: 'In-store promo cards',
      expiresAt: '2025-12-31T23:59:59Z',
    }),
  }
);

const data = await response.json();
// Save codes immediately — they cannot be retrieved later
const codes = data.data.codes;
console.log(`Generated ${codes.length} codes`);

import requests

response = requests.post(
    "https://api.gamifyhost.com/v1/campaigns/codes/generate",
    headers={
        "X-API-Secret": "sk_live_your_secret_key",
        "Content-Type": "application/json",
    },
    json={
        "slug": "summer-promo",
        "batchSize": 100,
        "pointsValue": 500,
        "label": "In-store promo cards",
        "expiresAt": "2025-12-31T23:59:59Z",
    },
)

data = response.json()
codes = data["data"]["codes"]
print(f"Generated {len(codes)} codes")
# Save codes immediately — they cannot be retrieved later

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

String body = """
    {
        "slug": "summer-promo",
        "batchSize": 100,
        "pointsValue": 500,
        "label": "In-store promo cards",
        "expiresAt": "2025-12-31T23:59:59Z"
    }
    """;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.gamifyhost.com/v1/campaigns/codes/generate"))
    .header("X-API-Secret", "sk_live_your_secret_key")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

payload := strings.NewReader(`{
    "slug": "summer-promo",
    "batchSize": 100,
    "pointsValue": 500,
    "label": "In-store promo cards",
    "expiresAt": "2025-12-31T23:59:59Z"
}`)

req, _ := http.NewRequest("POST", "https://api.gamifyhost.com/v1/campaigns/codes/generate", payload)
req.Header.Set("X-API-Secret", "sk_live_your_secret_key")
req.Header.Set("Content-Type", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["data"])

$ch = curl_init('https://api.gamifyhost.com/v1/campaigns/codes/generate');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Secret: sk_live_your_secret_key',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'slug' => 'summer-promo',
        'batchSize' => 100,
        'pointsValue' => 500,
        'label' => 'In-store promo cards',
        'expiresAt' => '2025-12-31T23:59:59Z',
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
// Save codes immediately — they cannot be retrieved later
print_r($data['data']['codes']);

require 'net/http'
require 'json'

uri = URI('https://api.gamifyhost.com/v1/campaigns/codes/generate')
req = Net::HTTP::Post.new(uri)
req['X-API-Secret'] = 'sk_live_your_secret_key'
req['Content-Type'] = 'application/json'
req.body = {
  slug: 'summer-promo',
  batchSize: 100,
  pointsValue: 500,
  label: 'In-store promo cards',
  expiresAt: '2025-12-31T23:59:59Z'
}.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
# Save codes immediately — they cannot be retrieved later
puts "Generated #{data['data']['codes'].length} codes"

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Secret", "sk_live_your_secret_key");

var content = new StringContent(
    JsonSerializer.Serialize(new {
        slug = "summer-promo",
        batchSize = 100,
        pointsValue = 500,
        label = "In-store promo cards",
        expiresAt = "2025-12-31T23:59:59Z"
    }),
    Encoding.UTF8, "application/json");

var response = await client.PostAsync(
    "https://api.gamifyhost.com/v1/campaigns/codes/generate", content);
var json = await response.Content.ReadAsStringAsync();
// Save codes immediately — they cannot be retrieved later
Console.WriteLine(json);

import 'dart:convert';
import 'package:http/http.dart' as http;

final response = await http.post(
  Uri.parse('https://api.gamifyhost.com/v1/campaigns/codes/generate'),
  headers: {
    'X-API-Secret': 'sk_live_your_secret_key',
    'Content-Type': 'application/json',
  },
  body: jsonEncode({
    'slug': 'summer-promo',
    'batchSize': 100,
    'pointsValue': 500,
    'label': 'In-store promo cards',
    'expiresAt': '2025-12-31T23:59:59Z',
  }),
);

final data = jsonDecode(response.body);
// Save codes immediately — they cannot be retrieved later
print('Generated ${data['data']['codes'].length} codes');

Response

Status: 200 OK

{
  "status": "success",
  "data": {
    "batch": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "campaignId": "c1d2e3f4-a5b6-7890-1234-567890abcdef",
      "batchSize": 100,
      "pointsValue": 500,
      "label": "In-store promo cards",
      "expiresAt": "2025-12-31T23:59:59Z",
      "createdAt": "2025-07-15T10:00:00Z"
    },
    "codes": [
      "SUMM-AX7K9M2P",
      "SUMM-BF3D8N4Q",
      "SUMM-CG5H2R6T",
      "..."
    ],
    "count": 100,
    "gameUrl": "https://app.gamifyhost.com/campaign/summer-promo"
  }
}

Code Format

Codes follow the pattern PREFIX-XXXXXXXX where:

PREFIX — First 4 characters of the campaign slug (uppercased)
XXXXXXXX — 8 random characters from a reduced charset (no confusing characters like O/0/I/1/L)

Response Fields

Field	Type	Description
`batch`	`object`	Batch metadata
`batch.id`	`uuid`	Unique batch ID
`batch.batchSize`	`integer`	Number of codes generated
`batch.pointsValue`	`integer`	Points per code
`batch.label`	`string`	Batch label
`codes`	`string[]`	Array of plaintext codes
`count`	`integer`	Number of codes generated
`gameUrl`	`string`	Public campaign page URL

Use Cases

In-store promotions: Print codes on receipts, packaging, or promotional cards
Email campaigns: Include unique codes in marketing emails
Partner distributions: Share codes with influencers or affiliate partners
Event giveaways: Hand out codes at physical events or trade shows

Errors

Code	Message
`400`	`batchSize must be between 1 and 10000`
`400`	`pointsValue must be positive`
`404`	Campaign not found