Introduction

Welcome to the ReferralStack API documentation. ReferralStack is an AI-powered affiliate management platform that helps SaaS companies drive revenue through intelligent referral and affiliate programs.

💡 Seamless Integration

ReferralStack connects seamlessly with your existing tech stack, making it easy to get started without disrupting your workflow.

Key Capabilities

Manage Affiliates

Create, update, and track affiliate partners programmatically with full control over their profiles and performance metrics.

Track Referrals

Monitor conversions through custom links and coupon codes with real-time analytics and attribution tracking.

Configure Campaigns

Set up and manage multiple affiliate campaigns with custom rules, rewards, and tracking parameters.

Access Analytics

Retrieve detailed performance metrics, revenue reports, and conversion data for data-driven decisions.

Getting Started

Obtain Your API Key

Navigate to Settings → Integrations

Click Copy API Key

Copy and securely store your API key

Make Your First Request

Try fetching your affiliate list to verify your API key works:

Expected Response:

{
  "status": 200,
  "message": "Affiliates fetched successfully",
  "data": {
    "items": [
      {
        "id": "3f6a9c1e-8b44-4c6e-9d4f-2e6b8f4a1c92",
        "email": "john@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "status": "active",
        "workspaceId": "5bb8cbe6-67dc-4b07-853e-7ca5454f8512",
        "createdAt": "2025-01-15T10:30:00.000Z",
        "updatedAt": "2025-01-15T10:30:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 25,
      "total": 1,
      "totalPages": 1
    }
  }
}

Explore the Documentation

Continue reading to learn about all available endpoints, request parameters, and response formats. Each endpoint includes code examples in multiple languages.

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

TIP

You can generate your API key from your ReferralStack dashboard under Settings → Integrations. Keep your API key secure and never expose it in client-side code.

Example Request:

Error Response (Missing/Invalid API Key):

{
  "status": 401,
  "message": "Invalid API key. Please check your API key and try again."
}

Base URL

All API endpoints are relative to the base URL:

https://api.referralstack.ai/api/v1

Example Request:

HTTP Status Codes

Understanding these status codes will help you handle API responses effectively:

Status Code	Description	Common Causes
`200 OK`	Request succeeded	Successful GET, PUT, PATCH, DELETE requests
`201 Created`	Resource created successfully	Successful POST requests
`400 Bad Request`	Invalid request parameters	Missing required fields, invalid data format, validation errors
`401 Unauthorized`	Invalid or missing API key	Wrong API key, missing x-auth-referralstack header
`403 Forbidden`	Insufficient permissions	Trying to access resources outside your plan
`404 Not Found`	Resource not found	Invalid endpoint or resource ID
`422 Unprocessable Entity`	Validation error	Invalid data that fails business rules (e.g., Sequelize validation errors)
`429 Too Many Requests`	Rate limit exceeded	Too many requests in a short period
`500 Internal Server Error`	Server error	Unexpected server issue

Rate Limits

API rate limits are enforced per API key to ensure optimal performance for all users:

Limit	Description
5 requests per second	Per API key
Burst limit	5 concurrent requests

WARNING

When you exceed your rate limit, you'll receive a 429 Too Many Requests response. The response will include a Retry-After header (in seconds) indicating when you can make requests again.

Rate Limit Error Response:

{
  "status": 429,
  "message": "Rate limit exceeded. Please try again later."
}

Available Endpoints

Campaigns

GET /api/v1/campaigns/list - List all campaigns

GET /api/v1/campaigns - Get a specific campaign

POST /api/v1/campaigns - Create a new campaign

PUT /api/v1/campaigns - Update a campaign

DELETE /api/v1/campaigns - Delete a campaign

Affiliates

GET /api/v1/affiliates/list - List all affiliates

GET /api/v1/affiliates - Get a specific affiliate

POST /api/v1/affiliates - Create a new affiliate

PUT /api/v1/affiliates - Update an affiliate

DELETE /api/v1/affiliates - Delete an affiliate

Links

GET /api/v1/links - Get a specific link

POST /api/v1/links - Create a new referral link

DELETE /api/v1/links - Delete a referral link

Commissions

GET /api/v1/commissions/list - List commissions

GET /api/v1/commissions - Get a specific commission

POST /api/v1/commissions - Create a new commission

PUT /api/v1/commissions - Update a commission

DELETE /api/v1/commissions - Delete a commission

Referred Users

GET /api/v1/referred-users/list - List referred users

GET /api/v1/referred-users - Get a specific referred user by email

POST /api/v1/referred-users - Create a new referred user

PUT /api/v1/referred-users - Update a referred user

DELETE /api/v1/referred-users - Delete a referred user

Example Requests

Create an Affiliate

Response:

{
  "status": 200,
  "message": "Affiliates fetched successfully",
  "data": {
    "id": "3f6a9c1e-8b44-4c6e-9d4f-2e6b8f4a1c92",
    "email": "john@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "status": "active"
  }
}

Validation Error Example

Error Response:

{
  "status": 400,
  "message": "Validation error",
  "errors": [
    {
      "type": "field",
      "msg": "email must be a valid email address",
      "path": "email",
      "location": "body"
    },
    {
      "type": "field",
      "msg": "campaignId is required",
      "path": "campaignId",
      "location": "body"
    }
  ]
}

Best Practices

Security Best Practices

Performance Optimization

Error Handling

Pagination Best Practices

Health Check

The API provides a health check endpoint that doesn't require authentication:

Response:

{
  "status": "ok",
  "service": "public-apis",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Support

🤝 Need Help?

Our support team is here to assist you with any questions or issues you encounter.

Key Capabilities#

Getting Started#

Authentication#

Base URL#

HTTP Status Codes#

Rate Limits#

Available Endpoints#

Campaigns#

Affiliates#

Links#

Commissions#

Referred Users#

Example Requests#

Create an Affiliate#

Validation Error Example#

Best Practices#

Health Check#

Support#

Key Capabilities

Getting Started

Authentication

Base URL

HTTP Status Codes

Rate Limits

Available Endpoints

Campaigns

Affiliates

Links

Commissions

Referred Users

Example Requests

Create an Affiliate

Validation Error Example

Best Practices

Health Check

Support