Invitebase | REST API

Drive the whole referral loop with cURL against api.invitebase.com — no SDK required

This quickstart runs the entire referral loop from your terminal: create a campaign, register a referrer and mint their link, send the referred user's events, and watch the referral validate — all against https://api.invitebase.com/v1 with a test secret key. Use it to understand exactly what the SDKs do for you, or as the basis for a pure server-side integration.

Get your test secret key

In the dashboard, go to Developers → API keys and copy your test secret key. Secret keys are sent as a Bearer token and must stay server-side:

export INVITEBASE_SECRET_KEY=sk_test_...

The _test_ prefix selects test mode — same host, isolated data, never billed. All POST endpoints also accept an Idempotency-Key header so retries return the original result.

Create a campaign

The campaign carries the reward configuration (what the referrer earns once a referral validates). Its qualification gate — what the referred user must do, and within what window — is built in the Campaign Builder, not sent through the API.

curl https://api.invitebase.com/v1/campaigns \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Give a month, get a month",
    "reward": [
      {
        "method": "free_access",
        "recipient": "referrer",
        "free_access_duration": { "count": 1, "unit": "month" }
      }
    ]
  }'

Then open the campaign in the dashboard and build its gate — for this walkthrough, one condition on subscription_started restricted to plan: paid, within 14 days.

{
  "id": "7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15",
  "object": "campaign",
  "name": "Give a month, get a month",
  "status": "active",
  "mode": "test",
  "livemode": false
}

Create a referrer and their link

Referrers are your end-users who share. POST /v1/referrers is idempotent on external_id — call it whenever a user could become a referrer.

curl https://api.invitebase.com/v1/referrers \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "usr_123",
    "email": "sam@example.com"
  }'

{ "id": "6b1d4f9a-8e25-4c07-a3f6-1c5e9d7b2a84", "object": "referrer", "external_id": "usr_123" }

Mint their link in the campaign:

curl https://api.invitebase.com/v1/referral-links \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "referrer_id": "6b1d4f9a-8e25-4c07-a3f6-1c5e9d7b2a84",
    "campaign_id": "7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15"
  }'

{
  "id": "1e7c3b8f-5d20-4a96-8b4e-7f2a9c5d1e63",
  "object": "referral_link",
  "code": "a1b2c3",
  "url": "https://mycompany.refr.link/a1b2c3"
}

The url is what the referrer shares. Opening it in a browser records the click and creates the referral in the clicked state; the code is what ties the referred user's events back to this referrer.

Events are the raw material the qualification engine evaluates. The signup event carries referral_code — that is the moment attribution happens and the referral advances to signed_up.

curl https://api.invitebase.com/v1/events \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-usr_friend_1" \
  -d '{
    "name": "signup",
    "referred_user_id": "usr_friend_1",
    "referral_code": "a1b2c3"
  }'

{ "id": "4d7e9f2a-1b58-4c36-a0d9-8e5f3b6c2d14", "object": "event", "name": "signup", "mode": "test" }

Events return 202 — they are accepted, then processed through the gate engine asynchronously.

Send the qualifying event

Now the event your campaign gates on. Because the user is already attributed, no referral_code is needed — events match on referred_user_id.

curl https://api.invitebase.com/v1/events \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "subscription_started",
    "referred_user_id": "usr_friend_1",
    "properties": { "plan": "paid" }
  }'

The gate matches (subscription_started with plan: paid, inside the 14-day window), fraud checks run, and the referral validates.

Watch the referral validate

Read it back — filter by campaign, or fetch the referral directly:

curl "https://api.invitebase.com/v1/referrals?campaign_id=7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15" \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY"

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "5f8e2a1d-7c49-4b06-9e3a-2d8f6b4c1e57",
      "object": "referral",
      "status": "validated",
      "campaign_id": "7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15",
      "referrer_id": "6b1d4f9a-8e25-4c07-a3f6-1c5e9d7b2a84",
      "referred_user_id": "usr_friend_1",
      "gate_progress": [
        {
          "event": "subscription_started",
          "target": 1,
          "current": 1,
          "satisfied": true,
          "satisfied_at": "2026-07-09T14:03:12Z"
        }
      ],
      "is_billable": true,
      "mode": "test",
      "livemode": false
    }
  ]
}

status: "validated" is the state that matters — the referral passed your gates and the fraud checks. A reward record is created automatically (GET /v1/rewards?referral_id=5f8e2a1d-7c49-4b06-9e3a-2d8f6b4c1e57), and if you have a webhook endpoint registered, referral.validated and the grant event are delivered to it, HMAC-signed. The same referral is visible in the dashboard under your campaign, and both events appear in the Overview live feed.

REST API

Get your test secret key

Create a campaign

Create a referrer and their link

Send the referred user's signup

Send the qualifying event

Watch the referral validate

On this page