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:

{
  "status": "ok",
  "version": "1"
}

| Field | Type | Description | | --------- | -------- | ---------------------------------------- | | status | string | "ok" when the API is healthy | | version | string | The current API major version identifier |

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