> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/guides/using-orbit-samples).

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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.orbit.devotel.io/api/v1/referrals/programs" \
    -H "X-API-Key: dv_test_sk_YOUR_KEY"
  ```

  ```typescript Node.js theme={null}
  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());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```typescript Node.js theme={null}
  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());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_8fb2d1b7c00c4ec9/totals" \
    -H "X-API-Key: dv_test_sk_YOUR_KEY"
  ```

  ```typescript Node.js theme={null}
  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());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "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.

```json 404 theme={null}
{
  "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"
  }
}
```