Referrals.com Developer Portal

Build and automate referral programs with our REST API

Quick Start

The Referrals.com API uses API key authentication. Include your key in the X-API-Key header with every request.

1. Generate an API Key

Go to your dashboard settings or call the API key endpoint:

curl -X POST https://referrals.com/api/v1/members/api-key \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

2. Make Your First Request

curl https://referrals.com/api/v1/members/profile \
  -H "X-API-Key: ref_your_api_key_here"

3. Create a Brand

curl -X POST https://referrals.com/api/v1/brands \
  -H "X-API-Key: ref_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://mybrand.com", "description": "My Brand"}'

4. Create a Campaign

curl -X POST https://referrals.com/api/v1/campaigns \
  -H "X-API-Key: ref_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Summer Referral Program", "url_id": 1}'

Base URL

https://referrals.com/api/v1

All endpoints are relative to this base URL.

Authentication

All API requests (except public endpoints like plan listing) require authentication via the X-API-Key header.

You can also exchange email and password for a JWT token via POST /api/v1/auth/token.

Response Format

All responses follow a consistent JSON format:

// Success
{
  "success": true,
  "data": { ... }
}

// Error
{
  "success": false,
  "error": "Error description"
}

Pagination

List endpoints support pagination using ?page=1&limit=20. Maximum limit is 100.

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  }
}

API Sections

Authentication

Token exchange and API key management

2 endpoints

Members

Registration, profile management

3 endpoints

Brands

Create and manage brands with analytics

4 endpoints

Campaigns

Full campaign lifecycle management

4 endpoints

Participants

View and manage referral participants

2 endpoints

Webhooks

3 endpoints

Integrations

Zapier, MailChimp, and Shopify integrations

3 endpoints

Billing

View available subscription plans

1 endpoint

View Full API Documentation