Referrals

Worked referrals samples

The endpoint list below documents every operation’s parameters; this overlay walks a referral program the way a dashboard or ledger integration actually uses it: read the program list → read the leaderboard → read program-wide totals ↓ and handle a 404 when a guessed id misses. Every request uses your API key (X-API-Key) against https://api.orbit.devotel.io/api/v1/referrals/programs. The response envelope is { data, meta } on success and { error, meta } on failure — four shapes total; see How to read a worked sample. Every response carries meta.request_id and meta.timestamp. Quote the request id when you report a failure; support can trace the request end-to-end from it. Run samples with a sandbox (dv_test_sk_*) key — they understand sandbox as signed with meta.test_mode: true and never hit the live ledger.

1. List referral programs

GET /api/v1/referrals/programs returns every program in your workspace — enabled or disabled — with its reward type, per-side reward configs, target URL, referral window, and enabled flag. Use this to page through programs before drilling into one by id.

curl -X GET "https://api.orbit.devotel.io/api/v1/referrals/programs" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/referrals/programs",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "programs": [
      {
        "id": "rpg_8fb2d1b7c00c4ec9",
        "name": "Checkout-Refer-A-Friend",
        "reward_type": "credit",
        "reward_value": "$10 account credit",
        "enabled": true,
        "target_url": "https://brand.example/signup",
        "start_at": "2026-01-01T00:00:00.000Z",
        "end_at": "2026-12-31T23:59:59.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_rpg_list",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Field notes a reader will hit on first integration:

reward_type is credit, discount_code, or custom. A credit reward pays into your wallet balance when a conversion is marked paid; discount and custom rewards run through the shared incentive engine.
enabled: false suppresses new code minting without deleting the program; pair it with the update endpoint below to toggle rollout.
Programs are created enabled unless you pass enabled: false on create.

2. Read the program leaderboard

GET /api/v1/referrals/programs/{id}/leaderboard returns the top referrers of one program — each referral code’s visits, signups, and paid rewards — with a human-readable referrer label beside the contact id. The limit query parameter (default 25, max 100) caps the page size. For aggregation over the whole program rather than the truncated top page, use the totals endpoint below.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_8fb2d1b7c00c4ec9/leaderboard?limit=50" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_8fb2d1b7c00c4ec9/leaderboard?limit=50",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "leaderboard": [
      {
        "rank": 1,
        "referral_code": "ref_abc123",
        "referrer_contact_id": "cnt_8fb2d1b7c00c4ec9",
        "referrer_label": "Maya Patel",
        "visits": 1420,
        "signups": 37,
        "paid_rewards": 35
      }
    ]
  },
  "meta": {
    "request_id": "req_rpg_leaderboard",
    "timestamp": "2026-08-26T12:02:00.000Z"
  }
}

3. Read program-wide totals

GET /api/v1/referrals/programs/{id}/totals aggregates over every referral code in the program — distinct referrer count, total signups, and total paid rewards — with no leaderboard page-size limit. Prefer this to summing the leaderboard when your stat card covers the whole program.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_8fb2d1b7c00c4ec9/totals" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_8fb2d1b7c00c4ec9/totals",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "total_referrers": 312,
    "total_signups": 4910,
    "total_paid_rewards": 4312
  },
  "meta": {
    "request_id": "req_rpg_totals",
    "timestamp": "2026-08-26T12:03:00.000Z"
  }
}

4. Errors

Errors follow the { error, meta } envelope. The failure every client hits: 404 — no matching program. A guessed program id, a deleted program, or a cross-workspace read returns RESOURCE_NOT_FOUND. Do not retry; refresh the program list first.

404

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "No referral program with that id exists in this workspace.",
    "status": 404
  },
  "meta": {
    "request_id": "req_rpg_err",
    "timestamp": "2026-08-26T12:04:00.000Z"
  }
}

API Reference

All Endpoints

Worked referrals samples

1. List referral programs

2. Read the program leaderboard

3. Read program-wide totals

4. Errors

​Worked referrals samples

​1. List referral programs

​2. Read the program leaderboard

​3. Read program-wide totals

​4. Errors

Worked referrals samples

1. List referral programs

2. Read the program leaderboard

3. Read program-wide totals

4. Errors