Award Points

POST /v1/points/award

Awards points to a user based on a configured reward rule. Creates the user automatically if they don’t exist. The number of points awarded is determined by the reward rule matching the eventType in your dashboard.

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	Must match a configured reward rule (e.g. signup, purchase, referral)
displayName	string	No	User’s display name (created/updated on the user record)
email	string	No	User’s email (created/updated on the user record)
metadata	object	No	Arbitrary key-value data stored with the ledger entry
reference	string	No	Idempotency key — duplicate references for the same event type are rejected

Request Examples

cURL

curl -X POST https://api.gamifyhost.com/v1/points/award \
  -H "X-API-Secret: sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_12345",
    "eventType": "signup",
    "displayName": "Alice",
    "email": "alice@example.com",
    "metadata": {
      "source": "ios_app",
      "campaign": "summer_2025"
    },
    "reference": "ref_signup_user12345"
  }'

JavaScript

const response = await fetch('https://api.gamifyhost.com/v1/points/award', {
  method: 'POST',
  headers: {
    'X-API-Secret': 'sk_live_your_secret_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 'user_12345',
    eventType: 'signup',
    displayName: 'Alice',
    email: 'alice@example.com',
    metadata: { source: 'ios_app', campaign: 'summer_2025' },
    reference: 'ref_signup_user12345',
  }),
});

const data = await response.json();
console.log(`Awarded ${data.data.pointsAwarded} pts, balance: ${data.data.userBalance}`);

Python

import requests

response = requests.post(
    "https://api.gamifyhost.com/v1/points/award",
    headers={
        "X-API-Secret": "sk_live_your_secret_key",
        "Content-Type": "application/json",
    },
    json={
        "userId": "user_12345",
        "eventType": "signup",
        "displayName": "Alice",
        "email": "alice@example.com",
        "metadata": {"source": "ios_app", "campaign": "summer_2025"},
        "reference": "ref_signup_user12345",
    },
)

data = response.json()
print(f"Awarded {data['data']['pointsAwarded']} pts, balance: {data['data']['userBalance']}")

Java

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

HttpClient client = HttpClient.newHttpClient();

String body = """
    {
        "userId": "user_12345",
        "eventType": "signup",
        "displayName": "Alice",
        "email": "alice@example.com",
        "metadata": {
            "source": "ios_app",
            "campaign": "summer_2025"
        },
        "reference": "ref_signup_user12345"
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.gamifyhost.com/v1/points/award"))
    .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": "signup",
    "displayName": "Alice",
    "email": "alice@example.com",
    "metadata": {"source": "ios_app", "campaign": "summer_2025"},
    "reference": "ref_signup_user12345"
}`)

req, _ := http.NewRequest("POST", "https://api.gamifyhost.com/v1/points/award", 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/points/award');
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' => 'signup',
        'displayName' => 'Alice',
        'email' => 'alice@example.com',
        'metadata' => ['source' => 'ios_app', 'campaign' => 'summer_2025'],
        'reference' => 'ref_signup_user12345',
    ]),
]);

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

$data = json_decode($response, true);
echo "Awarded {$data['data']['pointsAwarded']} pts, balance: {$data['data']['userBalance']}\n";

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.gamifyhost.com/v1/points/award')
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: 'signup',
  displayName: 'Alice',
  email: 'alice@example.com',
  metadata: { source: 'ios_app', campaign: 'summer_2025' },
  reference: 'ref_signup_user12345'
}.to_json

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

C#

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

var content = new StringContent(
    """
    {
        "userId": "user_12345",
        "eventType": "signup",
        "displayName": "Alice",
        "email": "alice@example.com",
        "metadata": {"source": "ios_app", "campaign": "summer_2025"},
        "reference": "ref_signup_user12345"
    }
    """,
    System.Text.Encoding.UTF8,
    "application/json"
);

var response = await client.PostAsync("https://api.gamifyhost.com/v1/points/award", 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/points/award'),
  headers: {
    'X-API-Secret': 'sk_live_your_secret_key',
    'Content-Type': 'application/json',
  },
  body: jsonEncode({
    'userId': 'user_12345',
    'eventType': 'signup',
    'displayName': 'Alice',
    'email': 'alice@example.com',
    'metadata': {'source': 'ios_app', 'campaign': 'summer_2025'},
    'reference': 'ref_signup_user12345',
  }),
);

final data = jsonDecode(response.body);
print('Awarded ${data['data']['pointsAwarded']} pts, balance: ${data['data']['userBalance']}');

Response

Status: 200 OK

{
  "message": "Points awarded successfully",
  "code": 200,
  "status": "success",
  "data": {
    "ledgerId": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
    "userId": "user_12345",
    "eventType": "signup",
    "pointsAwarded": 500,
    "userBalance": 5500,
    "reference": "ref_signup_user12345",
    "createdAt": "2025-07-15T10:00:00Z"
  }
}

Response Fields

Field	Type	Description
ledgerId	uuid	Unique ledger entry ID
userId	string	The user who received points
eventType	string	The event type that triggered the award
pointsAwarded	integer	Number of points awarded (from the matching reward rule)
userBalance	integer	User’s total balance after the award
reference	string	The idempotency reference (if provided)
createdAt	datetime	ISO 8601 timestamp

Errors

Code	Message
400	Invalid request body / validation error
404	No reward rule found for event type
409	Duplicate reference — points already awarded for this reference