Developer Documentation

Build Powerful Referral Systems

Everything you need to integrate ReferAgent into your application. RESTful API, JavaScript SDK, and webhook support.

Quick StartAPI Reference
Getting Started
Set up your first referral campaign in under 5 minutes
API Reference
Complete documentation of all API endpoints
Webhooks
Real-time event notifications for your app
Integrations
Connect with your existing tools and platforms

Quick Start

Get up and running with ReferAgent in just a few lines of code.

1

Install the SDK

terminal
npm install @referagent/sdk
2

Initialize the client

javascript
import { ReferAgent } from '@referagent/sdk'

const agent = new ReferAgent({
  apiKey: process.env.REFERAGENT_KEY
})
3

Create your first campaign

javascript
const campaign = await agent.campaigns.create({
  name: 'Summer Launch',
  platform: 'twitter',
  targetUrl: 'https://yourapp.com/signup',
  rewardType: 'token',
  rewardValue: 50
})
4

Generate referral links

javascript
const link = await agent.links.create({
  campaignId: campaign.id,
  alias: 'SUMMER24' // optional custom alias
})

// Returns: https://ref.ag/SUMMER24

API Reference

Authentication

All API requests require authentication via API key in the header:

Authorization: Bearer YOUR_API_KEY

Security Requirements

  • API keys must start with ra_live_
  • Each API key is scoped to a specific user account
  • Users can only access/modify their own campaigns and data
  • API keys can be scoped with read and/or write permissions
  • Full API keys are only shown once when created - store them securely

Rate Limiting

API endpoints are rate-limited to prevent abuse:

  • Read operations: 120 requests per minute
  • Write operations: 30 requests per minute
  • Tracking endpoints: 100 requests per minute

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

CORS

API endpoints support CORS for cross-origin requests. Configure allowed origins via the ALLOWED_ORIGINS environment variable.

Pricing & Tokens

ReferAgent uses a simple per-campaign pricing model:

  • Campaign creation: 25 tokens (one-time)
  • Everything else: Free (unlimited clicks, conversions, links, analytics)
  • Domain connections: Free

Purchase tokens on AgentDAO. Once you create a campaign, you get unlimited usage forever.

Endpoints

POST/api/campaigns
GET/api/campaigns
GET/api/campaigns/:id
POST/api/campaigns/:id/links
GET/api/campaigns/:id/analytics
POST/api/conversions

Webhooks

Receive real-time notifications when events occur in your campaigns.

campaign.created

New campaign created

link.clicked

Referral link clicked

conversion.completed

Conversion tracked

reward.issued

Reward distributed

webhook payload
{
  "event": "conversion.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "campaignId": "camp_abc123",
    "linkCode": "SUMMER24",
    "conversionId": "conv_xyz789",
    "value": 99.99,
    "metadata": {
      "plan": "pro",
      "source": "twitter"
    }
  }
}

Integrations

Connect ReferAgent with your existing tools and platforms.

Stripe

Track purchases as conversions

Segment

Unified analytics pipeline

Slack

Real-time notifications

Zapier

1000+ app integrations

Discord

Community notifications

Custom Webhooks

Build your own

Need Help?

Our team is here to help you integrate ReferAgent into your application.

Contact SupportGitHub Discussions