Record Campaign Event

POST /v1/campaigns/{slug}/events

Records a user event in the campaign. The campaign engine evaluates the event against configured mechanics and returns the result, including points earned, milestone progress, and instant-win outcomes.

Authentication

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

Request Body

Field	Type	Required	Description
userId	string	Yes	The user’s ID in your system
eventType	string	Yes	Event type (e.g., purchase, signup, daily_login)
metadata	object	No	Arbitrary key-value data stored with the event

Request Examples

cURL

curl -X POST https://api.gamifyhost.com/v1/campaigns/summer-promo/events \
  -H "X-API-Secret: sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_12345",
    "eventType": "purchase",
    "metadata": {
      "amount": 49.99,
      "product": "premium_plan"
    }
  }'

JavaScript

const response = await fetch('https://api.gamifyhost.com/v1/campaigns/summer-promo/events', {
  method: 'POST',
  headers: {
    'X-API-Secret': 'sk_live_your_secret_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 'user_12345',
    eventType: 'purchase',
    metadata: { amount: 49.99, product: 'premium_plan' },
  }),
});

const data = await response.json();
console.log(`Earned ${data.data.pointsEarned} pts, total: ${data.data.totalPoints}`);

Python

import requests

response = requests.post(
    "https://api.gamifyhost.com/v1/campaigns/summer-promo/events",
    headers={
        "X-API-Secret": "sk_live_your_secret_key",
        "Content-Type": "application/json",
    },
    json={
        "userId": "user_12345",
        "eventType": "purchase",
        "metadata": {"amount": 49.99, "product": "premium_plan"},
    },
)

data = response.json()
print(f"Earned {data['data']['pointsEarned']} pts, total: {data['data']['totalPoints']}")

Java

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

String body = """
    {
        "userId": "user_12345",
        "eventType": "purchase",
        "metadata": {"amount": 49.99, "product": "premium_plan"}
    }
    """;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.gamifyhost.com/v1/campaigns/summer-promo/events"))
    .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());

Go

payload := strings.NewReader(`{
    "userId": "user_12345",
    "eventType": "purchase",
    "metadata": {"amount": 49.99, "product": "premium_plan"}
}`)

req, _ := http.NewRequest("POST", "https://api.gamifyhost.com/v1/campaigns/summer-promo/events", 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"])

PHP

$ch = curl_init('https://api.gamifyhost.com/v1/campaigns/summer-promo/events');
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([
        'userId' => 'user_12345',
        'eventType' => 'purchase',
        'metadata' => ['amount' => 49.99, 'product' => 'premium_plan'],
    ]),
]);

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

$data = json_decode($response, true);
echo "Earned {$data['data']['pointsEarned']} pts\n";

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.gamifyhost.com/v1/campaigns/summer-promo/events')
req = Net::HTTP::Post.new(uri)
req['X-API-Secret'] = 'sk_live_your_secret_key'
req['Content-Type'] = 'application/json'
req.body = {
  userId: 'user_12345',
  eventType: 'purchase',
  metadata: { amount: 49.99, product: 'premium_plan' }
}.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
puts "Earned #{data['data']['pointsEarned']} pts"

C#

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

var content = new StringContent(
    JsonSerializer.Serialize(new {
        userId = "user_12345",
        eventType = "purchase",
        metadata = new { amount = 49.99, product = "premium_plan" }
    }),
    Encoding.UTF8, "application/json");

var response = await client.PostAsync(
    "https://api.gamifyhost.com/v1/campaigns/summer-promo/events", content);
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

Dart

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

final response = await http.post(
  Uri.parse('https://api.gamifyhost.com/v1/campaigns/summer-promo/events'),
  headers: {
    'X-API-Secret': 'sk_live_your_secret_key',
    'Content-Type': 'application/json',
  },
  body: jsonEncode({
    'userId': 'user_12345',
    'eventType': 'purchase',
    'metadata': {'amount': 49.99, 'product': 'premium_plan'},
  }),
);

final data = jsonDecode(response.body);
print('Earned ${data['data']['pointsEarned']} pts');

Response

Status: 200 OK

{
  "status": "success",
  "data": {
    "pointsEarned": 100,
    "totalPoints": 750,
    "instantWin": {
      "won": true,
      "prizeTier": "Gold",
      "pointsEarned": 500,
      "winCode": "SUMM-AX7K9M2P",
      "message": "Congratulations! You won the Gold prize!"
    },
    "message": "Event recorded successfully"
  }
}

Response Fields

Field	Type	Description
pointsEarned	integer	Points earned from the event
totalPoints	integer	Participant’s total points in this campaign
instantWin	object	Present if instant-win mechanic is enabled
instantWin.won	boolean	Whether the user won
instantWin.prizeTier	string	Name of the prize tier (if won)
instantWin.winCode	string	Unique redemption code (if won)
message	string	Human-readable status message

Errors

Code	Message
400	Invalid request body
404	Campaign not found or not active
409	User has exceeded maximum plays