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.

Optionally, you can send a one-time play link via email that allows the user to play games directly without embedding the widget in your app.

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 (required if sendPlayLink is true)
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
sendPlayLink	boolean	No	If true, generates a one-time play link and sends it to the user’s email
linkExpiresInHours	integer	No	Link expiration time in hours (1-720). Default: 48

Request Examples

Basic (Award Points Only)

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']}")

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"])

With Play Link (Sends Email to User)

Tip

When you include sendPlayLink: true and provide an email, the user receives a branded email with a one-time link to play games. This is useful when you don’t have the widget embedded in your app.

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",
    "reference": "ref_signup_user12345",
    "sendPlayLink": true,
    "linkExpiresInHours": 72
  }'

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',
    reference: 'ref_signup_user12345',
    sendPlayLink: true,
    linkExpiresInHours: 72,
  }),
});

const data = await response.json();
console.log(`Play link: ${data.data.playLink.url}`);
console.log(`Expires: ${data.data.playLink.expiresAt}`);

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",
        "reference": "ref_signup_user12345",
        "sendPlayLink": True,
        "linkExpiresInHours": 72,
    },
)

data = response.json()
print(f"Play link: {data['data']['playLink']['url']}")
print(f"Expires: {data['data']['playLink']['expiresAt']}")

Go

payload := strings.NewReader(`{
    "userId": "user_12345",
    "eventType": "signup",
    "displayName": "Alice",
    "email": "alice@example.com",
    "reference": "ref_signup_user12345",
    "sendPlayLink": true,
    "linkExpiresInHours": 72
}`)

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)

data := result["data"].(map[string]interface{})
playLink := data["playLink"].(map[string]interface{})
fmt.Printf("Play link: %s\n", playLink["url"])

Response

Status: 201 Created

Basic Response (Without Play Link)

{
  "message": "Points awarded successfully",
  "code": 201,
  "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 With Play Link

When sendPlayLink: true and email is provided:

{
  "message": "Points awarded successfully",
  "code": 201,
  "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",
    "playLink": {
      "url": "https://play.gamifyhost.com/play?token=...",
      "expiresAt": "2025-07-18T10:00:00Z",
      "emailSent": true
    }
  }
}

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
playLink	object	Present only when sendPlayLink is true and email is provided
playLink.url	string	The one-time play link URL
playLink.expiresAt	datetime	When the link expires
playLink.emailSent	boolean	Whether the email was sent successfully

Play Link Behavior

Note

Play links are one-time use. Once the user opens the link and the page loads, the token is marked as redeemed and cannot be used again.

• The link opens the GamifyHost play app at play.gamifyhost.com and automatically initializes the widget with the user’s context
• The user can immediately start playing games using their awarded points
• Partners can customize the email content (subject, heading, body, CTA text) via the dashboard under Rewards → Message Template
• If you have branding configured (logo, colors), both the email and the play app will reflect your brand
• If the link expires or has already been used, the user sees a friendly error message

Use Cases

Email Campaigns: Award points for completing a survey, then send a play link so users can redeem rewards without logging into your app.

Referral Programs: When a user refers a friend, award them points and send a play link via email so they can play games immediately.

Re-engagement: Award inactive users bonus points and send them a play link to bring them back.

No-App Integration: If you don’t have a mobile app or website where you can embed the widget, use play links to let users access games via email.

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