Get User Profile

GET /v1/user-journeys/users/{externalId}

Returns the full enriched user profile including lifecycle stage, engagement tier, engagement score, pre-computed metrics, and personalized campaign recommendations.

Authentication

Header	Required	Value
X-API-Key	Yes	Your public key

Path Parameters

Parameter	Type	Required	Description
externalId	string	Yes	The user’s external ID in your system

Request Examples

cURL

curl https://api.gamifyhost.com/v1/user-journeys/users/user_12345 \
  -H "X-API-Key: pk_live_your_public_key"

JavaScript

const response = await fetch(
  'https://api.gamifyhost.com/v1/user-journeys/users/user_12345',
  {
    headers: { 'X-API-Key': 'pk_live_your_public_key' },
  }
);

const { data } = await response.json();
console.log(`${data.displayName} — ${data.lifecycleStage} / ${data.engagementTier}`);
console.log(`Score: ${data.engagementScore}, Plays 7d: ${data.plays7d}`);
console.log('Recommendations:', data.recommendations);

Python

import requests

response = requests.get(
    "https://api.gamifyhost.com/v1/user-journeys/users/user_12345",
    headers={"X-API-Key": "pk_live_your_public_key"},
)

data = response.json()["data"]
print(f"{data['displayName']} — {data['lifecycleStage']} / {data['engagementTier']}")
for rec in data["recommendations"]:
    print(f"  [{rec['priority']}] {rec['name']}: {rec['reason']}")

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": "engaged",
    "engagementTier": "regular",
    "engagementScore": 62.5,
    "totalPlays": 45,
    "plays7d": 8,
    "plays30d": 22,
    "pointsEarned7d": 340,
    "pointsEarned30d": 1250,
    "campaignsJoined": 3,
    "winRate": 0.35,
    "avgSessionGapMin": 42.5,
    "totalEvents": 128,
    "tags": { "plan": "premium" },
    "metadata": { "signupDate": "2025-01-15" },
    "recommendations": [
      {
        "type": "referral",
        "name": "Refer a Friend",
        "reason": "Engaged user — leverage satisfaction for growth",
        "priority": "high"
      },
      {
        "type": "leaderboard_challenge",
        "name": "Weekly Leaderboard",
        "reason": "Competitive element to deepen engagement",
        "priority": "medium"
      }
    ]
  }
}

Profile Fields

Field	Type	Description
externalId	string	Your unique user identifier
displayName	string	User’s display name
email	string	User’s email
country	string	ISO 3166-1 alpha-2 country code
device	string	mobile, desktop, or tablet
source	string	Acquisition channel
firstSeenAt	string	First interaction timestamp (ISO 8601)
lastSeenAt	string	Last interaction timestamp (ISO 8601)
lifecycleStage	string	new, active, engaged, power_user, at_risk, churned
engagementTier	string	casual, regular, power_user, whale
engagementScore	number	0–100 composite engagement score
totalPlays	integer	Total game plays across all time
plays7d	integer	Game plays in the last 7 days
plays30d	integer	Game plays in the last 30 days
pointsEarned7d	integer	Points earned in the last 7 days
pointsEarned30d	integer	Points earned in the last 30 days
campaignsJoined	integer	Number of distinct campaigns participated in
winRate	number	Win rate across all game plays (0–1)
totalEvents	integer	Total events tracked
recommendations	array	Personalized campaign recommendations

Errors

Code	Message
404	User not found