This guide explains the fundamental concepts and data model that power the DRIP ecosystem. Understanding these concepts is essential for building effective integrations.
Terminology: In the dashboard UI, a “Realm” is sometimes labeled as “Project”. They refer to the same thing.

​
API Client Types

DRIP supports two distinct types of API clients:

​
Realm Clients

Purpose: Direct integration with your own realm
Scope: Single realm access
Authorization: Automatic access to your realm
Use Cases: Custom dashboards, internal automation, realm-specific tools

​
App Clients

Purpose: Multi-realm applications for the broader ecosystem
Scope: Multiple realm access with explicit authorization
Authorization: Platform approval + individual realm authorization
Use Cases: Third-party integrations, marketplace apps, SaaS tools
The type of client determines your authorization flow and available permissions. Choose based on whether you’re building for your own realm or the broader DRIP ecosystem.

​
Data Model Overview

DRIP’s architecture is built around these core entities:

​
Realms

A Realm (or Project) represents your community or server - it’s the top-level container for all resources.

​
Key Properties

  • ID: Unique identifier for the realm
  • Name: Display name of your community
  • Subdomain: Custom subdomain (e.g., yourname.drip.re)
  • Settings: Configuration for features, branding, permissions
  • Members: All users who have joined the realm

​
Example Realm Object

{
  "id": "507f1f77bcf86cd799439011",
  "name": "My Gaming Community",
  "description": "The best gaming community on Discord",
  "subdomain": "mygaming",
  "serverId": "123456789012345678",
  "ownerId": "507f1f77bcf86cd799439012",
  "level": 5,
  "premiumLevel": 2,
  "published": true,
  "verified": true
}
Most API operations are scoped to a specific realm. You’ll need your Realm ID for nearly every API call.

​
Members

Realm Members represent users who have joined your community and can earn points, complete quests, and make purchases.

​
Key Properties

  • ID: Unique identifier for the member’s account
  • Realm Membership: Specific membership details for this realm
  • Point Balances: Current balances for each point type
  • Credentials: Connected accounts (Discord, Twitter, wallets)
  • Activity: Join date, last visit, engagement metrics

​
Member Search Types

You can search for members using different identifiers:
Search TypeDescriptionExample
drip-idInternal DRIP member ID507f1f77bcf86cd799439013
discord-idDiscord user ID123456789012345678
twitter-idTwitter/X user ID987654321
walletCrypto wallet address0x742d35Cc6634C0532925a3b8D23
emailEmail address[email protected]
usernameDisplay usernamegamerpro123

​
Example Member Object

{
  "id": "507f1f77bcf86cd799439013",
  "realmMemberId": "507f1f77bcf86cd799439014",
  "username": "gamerpro123",
  "displayName": "Gamer Pro",
  "imageUrl": "https://cdn.drip.re/avatars/123.png",
  "joinedAt": "2024-01-15T10:30:00Z",
  "lastVisit": "2024-01-20T14:22:00Z",
  "pointBalances": [
    {
      "balance": 1500,
      "realmPoint": {
        "id": "507f1f77bcf86cd799439015",
        "name": "XP",
        "emoji": "⭐"
      }
    }
  ]
}

​
Points (Currencies)

Realm Points are customizable currencies that members can earn, spend, and transfer within your community.

​
Point Types

  • Primary Currency: Main point system (e.g., XP, Coins)
  • Secondary Currencies: Additional point types (e.g., Gems, Tokens)
  • Event Points: Temporary currencies for special events
  • Branded Points: Custom-branded currencies with logos

​
Key Operations

  • Award Points: Add points to a member’s balance
  • Deduct Points: Remove points (for purchases, penalties)
  • Transfer Points: Move points between members
  • Batch Updates: Update multiple balances at once

​
Example Point Balance Update

{
  "tokens": 100,
  "realmPointId": "507f1f77bcf86cd799439015"
}
Point operations are atomic - they either succeed completely or fail completely. This prevents double-spending and ensures data consistency.

​
Quests

Quests are gamified task systems that engage members through challenges, rewards, and progression.

​
Quest Structure

​
Components

ComponentPurposeExamples
QuestOverall challenge container”Weekly Challenges”, “Onboarding”
TaskIndividual steps within quest”Join Discord”, “Make 5 Posts”
TriggerEvents that activate tasksMessage sent, reaction added
ActionWhat happens when task completesAward points, assign role
ConditionRequirements to complete taskMinimum message length, specific channel

​
Quest States

  • Draft: Being created, not yet active
  • Active: Running and accepting completions
  • Paused: Temporarily stopped
  • Completed: Finished, no longer accepting new participants
  • Archived: Historical record, not visible to users

​
Store Items

Store Items allow members to spend their points on rewards, perks, and digital goods.

​
Item Types

  • Digital Rewards: Exclusive content, early access
  • Role Upgrades: Special Discord roles and permissions
  • Physical Items: Merchandise, gift cards (with shipping)
  • Experiences: Events, meetings, consultations

​
Key Properties

{
  "id": "507f1f77bcf86cd799439016",
  "name": "VIP Discord Role",
  "description": "Get exclusive VIP access and perks",
  "price": 1000,
  "realmPointId": "507f1f77bcf86cd799439015",
  "category": "roles",
  "inventory": 50,
  "purchaseLimit": 1,
  "active": true
}

​
Relationships and Workflows

​
Common Integration Patterns

​
Data Consistency

DRIP ensures data consistency through:
  • Atomic Operations: All-or-nothing transactions
  • Validation: Input validation and business rule enforcement
  • Audit Trails: Complete history of all changes
  • Rate Limiting: Prevents abuse and ensures system stability

​
Best Practices

Efficient Queries

  • Use specific search parameters
  • Implement pagination for large datasets
  • Cache frequently accessed data
  • Batch operations when possible

Error Handling

  • Always check response status codes
  • Implement retry logic with backoff
  • Log errors for debugging
  • Provide meaningful user feedback

Security

  • Validate all user inputs
  • Use least-privilege API keys
  • Implement rate limiting
  • Monitor for unusual activity

Performance

  • Use webhooks for real-time updates
  • Implement efficient caching strategies
  • Optimize database queries
  • Monitor API response times

​
Next Steps

Now that you understand DRIP’s core concepts, explore these integration guides:

Managing Members

Learn to search, update, and manage community members

Point Systems

Implement reward systems and point management

Quest Management

Create and manage gamified experiences

Webhooks

Set up real-time event notifications