Track / Enrich User

POST /v1/user-journeys/users

Creates or updates a user profile. If a profile with the same externalId already exists for your account and environment, the enrichment fields are updated. The externalId is your unique identifier for the user in your system.

Authentication

Header	Required	Value
X-API-Key	Yes	Your public key
Content-Type	Yes	application/json

Request Body

Field	Type	Required	Description
externalId	string	Yes	Your unique user identifier
displayName	string	No	User’s display name
email	string	No	User’s email address
phone	string	No	Phone number (max 20 chars)
country	string	No	ISO 3166-1 alpha-2 code (e.g., NG, US, GB)
device	string	No	Device type: mobile, desktop, tablet
source	string	No	Acquisition channel (e.g., organic, facebook_ads, referral)
tags	object	No	Custom key-value tags for filtering
metadata	object	No	Arbitrary metadata stored with the profile

Request Examples

cURL

curl -X POST https://api.gamifyhost.com/v1/user-journeys/users \
  -H "X-API-Key: pk_live_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_12345",
    "displayName": "Jane Doe",
    "email": "jane@example.com",
    "country": "NG",
    "device": "mobile",
    "source": "referral",
    "tags": { "plan": "premium", "cohort": "2025-Q1" },
    "metadata": { "signupDate": "2025-01-15" }
  }'

JavaScript

const response = await fetch('https://api.gamifyhost.com/v1/user-journeys/users', {
  method: 'POST',
  headers: {
    'X-API-Key': 'pk_live_your_public_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    externalId: 'user_12345',
    displayName: 'Jane Doe',
    email: 'jane@example.com',
    country: 'NG',
    device: 'mobile',
    source: 'referral',
    tags: { plan: 'premium', cohort: '2025-Q1' },
    metadata: { signupDate: '2025-01-15' },
  }),
});

const data = await response.json();
console.log('User tracked:', data.data.externalId);

Python

import requests

response = requests.post(
    "https://api.gamifyhost.com/v1/user-journeys/users",
    headers={
        "X-API-Key": "pk_live_your_public_key",
        "Content-Type": "application/json",
    },
    json={
        "externalId": "user_12345",
        "displayName": "Jane Doe",
        "email": "jane@example.com",
        "country": "NG",
        "device": "mobile",
        "source": "referral",
    },
)

data = response.json()
print(f"User tracked: {data['data']['externalId']}")

Go

payload := strings.NewReader(`{
    "externalId": "user_12345",
    "displayName": "Jane Doe",
    "email": "jane@example.com",
    "country": "NG",
    "device": "mobile",
    "source": "referral"
}`)

req, _ := http.NewRequest("POST", "https://api.gamifyhost.com/v1/user-journeys/users", payload)
req.Header.Set("X-API-Key", "pk_live_your_public_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"])

Response

Status: 200 OK

{
  "status": "success",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "partnerId": "partner-uuid",
    "externalId": "user_12345",
    "environment": "LIVE",
    "displayName": "Jane Doe",
    "email": "jane@example.com",
    "phone": "",
    "country": "NG",
    "device": "mobile",
    "source": "referral",
    "firstSeenAt": "2025-01-15T10:30:00Z",
    "lastSeenAt": "2025-03-05T14:22:00Z",
    "lifecycleStage": "new",
    "engagementTier": "casual",
    "engagementScore": 0,
    "totalPlays": 0,
    "plays7d": 0,
    "plays30d": 0,
    "pointsEarned7d": 0,
    "pointsEarned30d": 0,
    "campaignsJoined": 0,
    "winRate": 0,
    "totalEvents": 0,
    "tags": { "plan": "premium", "cohort": "2025-Q1" },
    "metadata": { "signupDate": "2025-01-15" }
  }
}

Errors

Code	Message
400	Invalid request body (missing externalId)
500	Failed to track user