Skip to main content

​
Overview

The Integration API powers your user-facing applications, providing secure access to challenges, rewards, achievements, and community features. Built for mobile apps, web frontends, and third-party integrations, it enables users to engage with your gamified community while maintaining data security and user privacy.

​
Base URL

https://{subdomain}.nudj.cx/api/v2/integration
Replace {subdomain} with your organization’s subdomain (e.g., acme-corp.nudj.cx).

​
Authentication

x-api-token: YOUR_INTEGRATION_TOKEN
Integration tokens are scoped to specific organizations and provide user-level access. Each request operates within the context of the authenticated user. See the Authentication guide for token management.

​
Core Capabilities

Challenge Participation

Join challenges, complete actions, track progress

Reward System

Browse catalog, purchase with points, redeem prizes

Social Features

Create posts, comment, like, follow community activity

Achievement Tracking

Unlock achievements, claim badges, view progress

Leaderboard Competition

View rankings, track position, compete with others

Profile Management

Update profile, view stats, manage preferences

​
User Experience Areas

​
🎮 Challenge & Action System

Complete actions within challenges to earn points, XP, and rewards.
User challenge lifecycle
  • Browse available challenges
  • View challenge details and requirements
  • Start/unlock challenges
  • Track progress through actions
  • Complete challenges for rewards
Key Endpoints:
  • GET /challenges - List available challenges
  • GET /challenges/{id} - Challenge details
  • POST /challenges/{id}/start - Begin challenge
  • POST /challenges/{id}/complete - Submit completion
  • POST /challenges/{id}/unlock - Unlock restricted challenges
// Start a challenge
await integration.challenges.start({
  challengeId: "challenge_123"
});
Action participation system
  • View action requirements
  • Submit action responses
  • Track completion status
  • Earn immediate rewards
Action Types:
  • Social media actions (follow, share, post)
  • Content engagement (read, watch, interact)
  • Community participation (post, comment, like)
  • External activities (surveys, links)
  • Custom actions
Key Endpoints:
  • GET /actions - List all actions
  • GET /actions/{id} - Action details
  • POST /action-participations - Submit action completion
  • GET /action-participations - View your participations
Organized challenge collections
  • Browse challenge categories
  • View group progress
  • Access themed challenges
  • Track group achievements
Key Endpoints:
  • GET /challenge-groups - List groups
  • GET /challenge-groups/{id} - Group details with challenges

​
🏆 Rewards & Incentives

Earn and redeem rewards through participation and achievements.
Browse and acquire rewards
  • View available rewards
  • Check point requirements
  • Purchase with points
  • View reward details
Key Endpoints:
  • GET /rewards - Browse catalog
  • GET /rewards/{id} - Reward details
  • POST /rewards/{id}/purchase - Buy with points
// Purchase a reward
await integration.rewards.purchase({
  rewardId: "reward_456",
  quantity: 1
});
Personal reward management
  • View owned rewards (assets)
  • Check giveaway entries
  • Redeem reward codes
  • Track reward history
Key Endpoints:
  • GET /me/rewards - Your reward assets
  • GET /me/rewards/{assetId} - Asset details
  • POST /me/rewards/{assetId}/redeem - Redeem reward
  • GET /me/reward-entries - Giveaway entries
  • POST /me/reward-entries/{id}/check - Check entry status

​
🎖️ Achievements & Progress

Track milestones and unlock achievements through engagement.
Milestone tracking system
  • View all achievements
  • Track progress toward unlocking
  • Claim unlocked achievements
  • Earn badges and rewards
Key Endpoints:
  • GET /achievements - List all achievements
  • GET /achievements/{id} - Achievement details
  • POST /achievements/{id}/claim - Claim unlocked achievement
// Claim an achievement
await integration.achievements.claim({
  achievementId: "achievement_789"
});
Recognition systems
  • View earned badges
  • Track active streaks
  • Monitor consistency bonuses
Key Endpoints:
  • GET /me/badges - Your badges
  • GET /me/streaks - Active streaks

​
📊 Leaderboards & Competition

Compete with other community members for top positions.
Competitive standings
  • View multiple leaderboard types
  • Check current rankings
  • Track your position
  • See nearby competitors
Key Endpoints:
  • GET /leaderboards/configs - Available leaderboards
  • GET /leaderboards/{id}/data - Full rankings
  • GET /leaderboards/{id}/position - Your position
// Get your leaderboard position
const position = await integration.leaderboards.getPosition({
  configId: "weekly_points"
});

​
💬 Social & Community

Engage with the community through posts, comments, and interactions.
Community content interaction
  • View community posts
  • Like and react to content
  • Create comments
  • Share thoughts
Key Endpoints:
  • GET /posts - List posts
  • GET /posts/{id} - Post details
  • POST /posts/{id}/like - Like a post
  • DELETE /posts/{id}/like - Unlike
  • GET /posts/{id}/comments - View comments
  • POST /posts/{id}/comments - Add comment
Discussion participation
  • Create new comments
  • Edit your comments
  • Reply to others
  • Engage in discussions
Key Endpoints:
  • POST /comments - Create comment
  • PUT /comments/{id} - Edit comment
  • PUT /posts/{postId}/comments/{commentId} - Update post comment
Community details and settings
  • View community information
  • Check active campaigns
  • See community themes
  • Access community links
Key Endpoints:
  • GET /communities - List communities
  • GET /communities/{identifier} - Community details
  • GET /campaigns - Active campaigns

​
👤 User Profile

Manage your profile and track personal progress.
Personal information and settings
  • View profile details
  • Update information
  • Manage preferences
  • Track statistics
Key Endpoints:
  • GET /me - Your profile
  • PATCH /me - Update profile
// Update profile
await integration.me.update({
  displayName: "NewUsername",
  bio: "Updated bio"
});
Special events and bonuses
  • View available events
  • Claim event rewards
  • Track special bonuses
Key Endpoints:
  • GET /events - Available events
  • POST /events/claim - Claim event rewards

​
API Resource Groups

  • Engagement
  • Rewards
  • Social
  • User
  • Configuration
ResourceOperationsPurpose
ChallengesGET, POST (start/complete/unlock)Challenge participation
ActionsGETView available actions
Action ParticipationsGET, POSTSubmit and track action completions
Challenge GroupsGETBrowse challenge categories
AchievementsGET, POST (claim)Milestone tracking
EventsGET, POST (claim)Special events and bonuses

​
Quick Start Examples

import { createIntegrationClient } from '@nudj-digital/api/integration';

const integration = createIntegrationClient({
  baseUrl: 'https://acme-corp.nudj.cx/api/v2/integration',
  headers: {
    'x-api-token': process.env.NUDJ_INTEGRATION_TOKEN
  }
});

// Get user profile and stats
const profile = await integration.me.get();
console.log(`Points: ${profile.points}, XP: ${profile.xp}`);

// Browse and join a challenge
const challenges = await integration.challenges.list({
  params: { status: 'active' }
});

const challenge = challenges.data[0];
await integration.challenges.start({
  challengeId: challenge.id
});

// Complete an action
await integration.actionParticipations.create({
  actionId: challenge.actions[0].id,
  data: {
    response: "completed"
  }
});

// Check leaderboard position
const position = await integration.leaderboards.getPosition({
  configId: "weekly_points"
});
console.log(`Rank: ${position.rank} with ${position.score} points`);

​
Common User Flows

  1. Get user profile (GET /me)
  2. View available challenges (GET /challenges)
  3. Start onboarding challenge (POST /challenges/{id}/start)
  4. Complete profile action (POST /action-participations)
  5. Claim welcome achievement (POST /achievements/{id}/claim)
  6. Check initial rewards (GET /me/rewards)
  1. Check active events (GET /events)
  2. View daily challenges (GET /challenges?type=daily)
  3. Complete daily actions (POST /action-participations)
  4. Check streak status (GET /me/streaks)
  5. View leaderboard position (GET /leaderboards/{id}/position)
  6. Browse and interact with posts (GET /posts, POST /posts/{id}/like)
  1. Browse reward catalog (GET /rewards)
  2. Check point balance (GET /me)
  3. Purchase reward (POST /rewards/{id}/purchase)
  4. View owned rewards (GET /me/rewards)
  5. Redeem reward code (POST /me/rewards/{assetId}/redeem)
  1. View community posts (GET /posts)
  2. Like interesting content (POST /posts/{id}/like)
  3. Add comments (POST /posts/{id}/comments)
  4. Complete social actions (POST /action-participations)
  5. Check social achievements (GET /achievements)

​
Response Format

All Integration API responses follow a consistent structure: 
{
  "data": {
    "id": "resource_123",
    "type": "challenge",
    "attributes": {
      "title": "Daily Challenge",
      "points": 100,
      "status": "active"
    },
    "relationships": {
      "actions": {
        "data": [
          { "id": "action_456", "type": "action" }
        ]
      }
    }
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

​
Error Handling

  • Error Codes
  • Error Response
CodeDescriptionResolution
UNAUTHORIZEDInvalid or missing tokenCheck authentication
FORBIDDENInsufficient permissionsVerify user access
NOT_FOUNDResource not foundCheck resource ID
VALIDATION_ERRORInvalid inputReview request data
ALREADY_COMPLETEDAction/challenge completedNo action needed
INSUFFICIENT_POINTSNot enough pointsUser needs more points

​
Best Practices

  • Performance
  • User Experience
  • Security
  • Cache responses appropriately (challenges, rewards catalog)
  • Paginate requests for large datasets
  • Batch where possible to reduce API calls
  • Use conditional requests with ETags when available

​
Pagination

Most list endpoints support pagination: 
// Pagination parameters
const params = {
  limit: 20,      // Items per page (max 100)
  skip: 40,       // Offset for pagination
  sort: '-created' // Sort by created date descending
};

const challenges = await integration.challenges.list({ params });

// Response includes pagination metadata
{
  data: [...],
  meta: {
    total: 150,
    limit: 20,
    skip: 40,
    hasMore: true
  }
}

​
Localization

The API supports multiple languages via headers: 
// Set language preference
const integration = createIntegrationClient({
  headers: {
    'x-api-token': token,
    'x-language': 'es-ES' // Spanish
  }
});

​
Rate Limiting

The Integration API enforces rate limits to ensure fair usage:
  • Check response headers for current limits
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: When limit resets
  • Implement exponential backoff on 429 responses

​
Webhooks

Configure webhooks to receive real-time updates:
  • Challenge completed
  • Achievement unlocked
  • Reward redeemed
  • Leaderboard position changed
Configure webhook endpoints in the Admin dashboard.

​
Support & Resources

API Reference

Detailed endpoint documentation

Authentication

Token management guide

SDKs

Client libraries
⌘I