Getting Started

Welcome to the Referral Reactor API. This guide walks you through everything you need to make your first successful API call — from obtaining credentials to reading the response.

Prerequisites

Before you begin, make sure you have:

• A Referral Reactor account on the Unlimited plan (API access is gated behind the api_access feature)
• Access to your organization's dashboard at app.referralreactor.com
• curl or a JavaScript/TypeScript runtime (Node.js 18+) installed locally

Step 1: Obtain an API Key

Referral Reactor API keys are Clerk-issued bearer tokens scoped to your organization.

To get your API key:

1. Sign in at app.referralreactor.com
2. Navigate to Settings → API Keys
3. Click Create API Key, give it a name, and select the scopes you need
4. Copy the key — it will only be shown once

Your key will look something like:

rr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep it secret. Never commit it to source control or expose it in client-side code.

Step 2: Make Your First Request

The GET /api/v1/health endpoint requires no authentication and is the simplest way to confirm the API is reachable.

curl

curl https://app.referralreactor.com/api/v1/health

To make an authenticated request (required for all other endpoints), pass your API key as a Bearer token:

curl https://app.referralreactor.com/api/v1/health \
  -H "Authorization: Bearer rr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

TypeScript / JavaScript

const BASE_URL = 'https://app.referralreactor.com';
const API_KEY = process.env.REFERRAL_REACTOR_API_KEY; // store in env, never hardcode

async function checkHealth(): Promise<void> {
  const response = await fetch(`${BASE_URL}/api/v1/health`, {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API error ${response.status}: ${error.message}`);
  }

  const data = await response.json();
  console.log('Health check:', data);
}

checkHealth();

Step 3: Interpret the Response

A successful health check returns HTTP 200 with a JSON body:

{
  "data": {
    "status": "healthy",
    "timestamp": "2026-08-28T17:10:00.000Z"
  },
  "requestId": "req_abc123",
  "timestamp": "2026-08-28T17:10:00.000Z"
}

| Field | Type | Description | | ---------------- | -------- | ---------------------------------------------- | | data.status | string | "healthy" when the API is up | | data.timestamp | string | ISO-8601 time the health check was served | | requestId | string | Identifier for this request, useful in support |

The response deliberately carries no build or deployment metadata.

If something goes wrong, the API returns a structured error body:

{
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "requestId": "req_abc123"
}

Use the requestId when contacting support — it uniquely identifies the failed request in our logs.

Next Steps

Now that you've made your first request, explore the rest of the docs:

• Authentication — Bearer token setup, available scopes, rate limiting, and error shapes
• API Reference — Interactive reference for all REST endpoints with live examples
• Webhooks — Event types, payload schemas, signature verification, and retry behavior
• Connect an AI assistant — Admins and business developers on the Unlimited plan can connect Claude, ChatGPT, Claude Code or Cursor from AI assistants in the account menu. The assistant acts as you, with your permissions.