> ## 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 API

> Referrals endpoints exposed by the Devotel CPaaS API

# Referrals API

Referrals endpoints exposed by the Devotel CPaaS API

**Base path:** `/api/v1/referrals/programs`

**Endpoint count:** 11

***

### List referral programs

<Note>
  `GET /api/v1/referrals/programs`
</Note>

List every referral program in your workspace — including disabled ones — with its reward type, reward configs, referral window, and enabled flag. Use this to page through programs before drilling into one by id.

<ParamField header="X-Test-Mode" type="string (enum: true|false)">
  Sandbox opt-in for Clerk-session-authenticated requests. Set to `true` to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response `meta.test_mode: true`. **Ignored for live API keys (`dv_live_sk_*`)** — server-to-server clients must use a test-prefixed key (`dv_test_sk_*`) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.
</ParamField>

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

    ```typescript Node.js theme={null}
    import { Orbit } from '@devotel-orbit/node'

    const orbit = new Orbit({
      apiKey: process.env.ORBIT_API_KEY!,
    })

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


    ```

    ```python Python theme={null}
    import os, requests

    headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
    r = requests.get("https://api.orbit.devotel.io/api/v1/referrals/programs", headers=headers)
    print(r.json())
    ```

    ```go Go theme={null}
    package main

    import (
    	"bytes"
    	"net/http"
    	"os"
    )

    func main() {
    	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/referrals/programs", nil)
    	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

    	http.DefaultClient.Do(req)
    }
    ```

    ```ruby Ruby theme={null}
    require 'net/http'
    require 'json'

    uri = URI('https://api.orbit.devotel.io/api/v1/referrals/programs')
    req = Net::HTTP::Get.new(uri)
    req['X-API-Key'] = ENV['ORBIT_API_KEY']


    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
    puts res.body
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init('https://api.orbit.devotel.io/api/v1/referrals/programs');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-Key: ' . getenv('ORBIT_API_KEY'),

    ]);

    echo curl_exec($ch);
    ```
  </CodeGroup>
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {},
    "meta": {
      "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
      "timestamp": "2026-08-26T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

***

### Get a referral program

<Note>
  `GET /api/v1/referrals/programs/{id}`
</Note>

Fetch a single referral program by id — its reward type, reward configs, target URL, referral window, and enabled flag. Returns `404` when no program with that id exists in your workspace.

<ParamField path="id" type="string" required>
  —
</ParamField>

<ParamField header="X-Test-Mode" type="string (enum: true|false)">
  Sandbox opt-in for Clerk-session-authenticated requests. Set to `true` to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response `meta.test_mode: true`. **Ignored for live API keys (`dv_live_sk_*`)** — server-to-server clients must use a test-prefixed key (`dv_test_sk_*`) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.
</ParamField>

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

    ```typescript Node.js theme={null}
    import { Orbit } from '@devotel-orbit/node'

    const orbit = new Orbit({
      apiKey: process.env.ORBIT_API_KEY!,
    })

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


    ```

    ```python Python theme={null}
    import os, requests

    headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
    r = requests.get("https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers)
    print(r.json())
    ```

    ```go Go theme={null}
    package main

    import (
    	"bytes"
    	"net/http"
    	"os"
    )

    func main() {
    	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", nil)
    	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

    	http.DefaultClient.Do(req)
    }
    ```

    ```ruby Ruby theme={null}
    require 'net/http'
    require 'json'

    uri = URI('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
    req = Net::HTTP::Get.new(uri)
    req['X-API-Key'] = ENV['ORBIT_API_KEY']


    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
    puts res.body
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-Key: ' . getenv('ORBIT_API_KEY'),

    ]);

    echo curl_exec($ch);
    ```
  </CodeGroup>
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {},
    "meta": {
      "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
      "timestamp": "2026-08-26T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

***

### List referral conversions

<Note>
  `GET /api/v1/referrals/programs/{id}/conversions`
</Note>

Page through a program's recorded conversions — the referral of a contact's signup. Each row carries the referrer and referee contact ids, human-readable identity labels for both sides, the reward status (`pending`, `paid`, `rejected`), and the rejection reason when rejected. Filter by `status` and page with `limit` (default 25, max 100) and `offset`. Returns the rows with the total count, limit, and offset.

<ParamField path="id" type="string" required>
  —
</ParamField>

<ParamField header="X-Test-Mode" type="string (enum: true|false)">
  Sandbox opt-in for Clerk-session-authenticated requests. Set to `true` to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response `meta.test_mode: true`. **Ignored for live API keys (`dv_live_sk_*`)** — server-to-server clients must use a test-prefixed key (`dv_test_sk_*`) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.
</ParamField>

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

    ```typescript Node.js theme={null}
    import { Orbit } from '@devotel-orbit/node'

    const orbit = new Orbit({
      apiKey: process.env.ORBIT_API_KEY!,
    })

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


    ```

    ```python Python theme={null}
    import os, requests

    headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
    r = requests.get("https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/conversions", headers=headers)
    print(r.json())
    ```

    ```go Go theme={null}
    package main

    import (
    	"bytes"
    	"net/http"
    	"os"
    )

    func main() {
    	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/conversions", nil)
    	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

    	http.DefaultClient.Do(req)
    }
    ```

    ```ruby Ruby theme={null}
    require 'net/http'
    require 'json'

    uri = URI('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/conversions')
    req = Net::HTTP::Get.new(uri)
    req['X-API-Key'] = ENV['ORBIT_API_KEY']


    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
    puts res.body
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/conversions');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-Key: ' . getenv('ORBIT_API_KEY'),

    ]);

    echo curl_exec($ch);
    ```
  </CodeGroup>
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {},
    "meta": {
      "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
      "timestamp": "2026-08-26T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

***

### Get the referral leaderboard

<Note>
  `GET /api/v1/referrals/programs/{id}/leaderboard`
</Note>

Return the top referrers of a program as a ranked leaderboard of referral codes — visits, signups, and paid rewards per code, with a human-readable referrer label alongside the contact id. The `limit` query parameter (default 25, max 100) caps the page size. To aggregate over the whole program rather than the truncated top page, use `GET /programs/{id}/totals`.

<ParamField path="id" type="string" required>
  —
</ParamField>

<ParamField header="X-Test-Mode" type="string (enum: true|false)">
  Sandbox opt-in for Clerk-session-authenticated requests. Set to `true` to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response `meta.test_mode: true`. **Ignored for live API keys (`dv_live_sk_*`)** — server-to-server clients must use a test-prefixed key (`dv_test_sk_*`) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.
</ParamField>

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

    ```typescript Node.js theme={null}
    import { Orbit } from '@devotel-orbit/node'

    const orbit = new Orbit({
      apiKey: process.env.ORBIT_API_KEY!,
    })

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


    ```

    ```python Python theme={null}
    import os, requests

    headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
    r = requests.get("https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/leaderboard", headers=headers)
    print(r.json())
    ```

    ```go Go theme={null}
    package main

    import (
    	"bytes"
    	"net/http"
    	"os"
    )

    func main() {
    	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/leaderboard", nil)
    	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

    	http.DefaultClient.Do(req)
    }
    ```

    ```ruby Ruby theme={null}
    require 'net/http'
    require 'json'

    uri = URI('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/leaderboard')
    req = Net::HTTP::Get.new(uri)
    req['X-API-Key'] = ENV['ORBIT_API_KEY']


    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
    puts res.body
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/leaderboard');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-Key: ' . getenv('ORBIT_API_KEY'),

    ]);

    echo curl_exec($ch);
    ```
  </CodeGroup>
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {},
    "meta": {
      "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
      "timestamp": "2026-08-26T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

***

### Get program-wide referral totals

<Note>
  `GET /api/v1/referrals/programs/{id}/totals`
</Note>

Aggregate referral totals over EVERY referral code in a program — distinct referrer count, total signups, and total paid rewards — with no leaderboard page-size limit. Use it for detail-page stat cards where summing the top-N leaderboard would undercount.

<ParamField path="id" type="string" required>
  —
</ParamField>

<ParamField header="X-Test-Mode" type="string (enum: true|false)">
  Sandbox opt-in for Clerk-session-authenticated requests. Set to `true` to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response `meta.test_mode: true`. **Ignored for live API keys (`dv_live_sk_*`)** — server-to-server clients must use a test-prefixed key (`dv_test_sk_*`) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.
</ParamField>

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

    ```typescript Node.js theme={null}
    import { Orbit } from '@devotel-orbit/node'

    const orbit = new Orbit({
      apiKey: process.env.ORBIT_API_KEY!,
    })

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


    ```

    ```python Python theme={null}
    import os, requests

    headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
    r = requests.get("https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/totals", headers=headers)
    print(r.json())
    ```

    ```go Go theme={null}
    package main

    import (
    	"bytes"
    	"net/http"
    	"os"
    )

    func main() {
    	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/totals", nil)
    	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

    	http.DefaultClient.Do(req)
    }
    ```

    ```ruby Ruby theme={null}
    require 'net/http'
    require 'json'

    uri = URI('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/totals')
    req = Net::HTTP::Get.new(uri)
    req['X-API-Key'] = ENV['ORBIT_API_KEY']


    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
    puts res.body
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/totals');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-Key: ' . getenv('ORBIT_API_KEY'),

    ]);

    echo curl_exec($ch);
    ```
  </CodeGroup>
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {},
    "meta": {
      "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
      "timestamp": "2026-08-26T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

***

### Count referral programs

<Note>
  `GET /api/v1/referrals/programs/count`
</Note>

Return just the total number of referral programs in your workspace (`{ total }`). Use it for dashboard badges and count cards without downloading the full program list.

<ParamField header="X-Test-Mode" type="string (enum: true|false)">
  Sandbox opt-in for Clerk-session-authenticated requests. Set to `true` to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response `meta.test_mode: true`. **Ignored for live API keys (`dv_live_sk_*`)** — server-to-server clients must use a test-prefixed key (`dv_test_sk_*`) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.
</ParamField>

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

    ```typescript Node.js theme={null}
    import { Orbit } from '@devotel-orbit/node'

    const orbit = new Orbit({
      apiKey: process.env.ORBIT_API_KEY!,
    })

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


    ```

    ```python Python theme={null}
    import os, requests

    headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
    r = requests.get("https://api.orbit.devotel.io/api/v1/referrals/programs/count", headers=headers)
    print(r.json())
    ```

    ```go Go theme={null}
    package main

    import (
    	"bytes"
    	"net/http"
    	"os"
    )

    func main() {
    	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/referrals/programs/count", nil)
    	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

    	http.DefaultClient.Do(req)
    }
    ```

    ```ruby Ruby theme={null}
    require 'net/http'
    require 'json'

    uri = URI('https://api.orbit.devotel.io/api/v1/referrals/programs/count')
    req = Net::HTTP::Get.new(uri)
    req['X-API-Key'] = ENV['ORBIT_API_KEY']


    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
    puts res.body
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init('https://api.orbit.devotel.io/api/v1/referrals/programs/count');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-Key: ' . getenv('ORBIT_API_KEY'),

    ]);

    echo curl_exec($ch);
    ```
  </CodeGroup>
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {},
    "meta": {
      "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
      "timestamp": "2026-08-26T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

***

### Create a referral program

<Note>
  `POST /api/v1/referrals/programs`
</Note>

Create a referral program for your workspace's contacts. A program defines the reward type (`credit`, `discount_code`, or `custom`), the human-readable `reward_value` label, and the optional per-side reward configs (`referrer_reward`, `referee_reward`). A credit reward pays into your wallet balance when a conversion is marked paid; discount and custom rewards go through the shared incentive engine. Optionally set a `target_url` to send referred visitors to a landing page other than your signup, and a `start_at` / `end_at` window to bound when referrals convert. Programs are created enabled unless you pass `enabled: false`. Returns the created program. Requires the owner, admin, or developer role.

<ParamField header="Idempotency-Key" type="string">
  Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the `Idempotency-Replay: true` response header.
</ParamField>

<ParamField header="X-Test-Mode" type="string (enum: true|false)">
  Sandbox opt-in for Clerk-session-authenticated requests. Set to `true` to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response `meta.test_mode: true`. **Ignored for live API keys (`dv_live_sk_*`)** — server-to-server clients must use a test-prefixed key (`dv_test_sk_*`) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.
</ParamField>

<RequestExample>
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X POST "https://api.orbit.devotel.io/api/v1/referrals/programs" \
      -H "X-API-Key: dv_live_sk_your_key_here" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```

    ```typescript Node.js theme={null}
    import { Orbit } from '@devotel-orbit/node'

    const orbit = new Orbit({
      apiKey: process.env.ORBIT_API_KEY!,
    })

    const res = await fetch('https://api.orbit.devotel.io/api/v1/referrals/programs', {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.ORBIT_API_KEY!,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({}),
    })
    console.log(await res.json())
    ```

    ```python Python theme={null}
    import os, requests

    headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
    headers["Content-Type"] = "application/json"
    r = requests.post("https://api.orbit.devotel.io/api/v1/referrals/programs", headers=headers, json={})
    print(r.json())
    ```

    ```go Go theme={null}
    package main

    import (
    	"bytes"
    	"net/http"
    	"os"
    )

    func main() {
    	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/referrals/programs", bytes.NewBuffer([]byte(`{}`)))
    	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
    	req.Header.Set("Content-Type", "application/json")
    	http.DefaultClient.Do(req)
    }
    ```

    ```ruby Ruby theme={null}
    require 'net/http'
    require 'json'

    uri = URI('https://api.orbit.devotel.io/api/v1/referrals/programs')
    req = Net::HTTP::Post.new(uri)
    req['X-API-Key'] = ENV['ORBIT_API_KEY']
    req['Content-Type'] = 'application/json'
    req.body = {}.to_json
    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
    puts res.body
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init('https://api.orbit.devotel.io/api/v1/referrals/programs');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-Key: ' . getenv('ORBIT_API_KEY'),
      'Content-Type: application/json',
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
    {}
    JSON);
    echo curl_exec($ch);
    ```
  </CodeGroup>
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {},
    "meta": {
      "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
      "timestamp": "2026-08-26T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

***

### Issue a referral code

<Note>
  `POST /api/v1/referrals/programs/{id}/codes`
</Note>

Mint a referral code for one of your contacts in the given program — or return the contact's existing code when one was already issued. Each code tracks its own visits, signups, and paid rewards, and referral links resolve through the public `/r/:code` redirect. Returns `404` when the program does not exist. Requires the owner, admin, or developer role.

<ParamField path="id" type="string" required>
  —
</ParamField>

<ParamField header="Idempotency-Key" type="string">
  Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the `Idempotency-Replay: true` response header.
</ParamField>

<ParamField header="X-Test-Mode" type="string (enum: true|false)">
  Sandbox opt-in for Clerk-session-authenticated requests. Set to `true` to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response `meta.test_mode: true`. **Ignored for live API keys (`dv_live_sk_*`)** — server-to-server clients must use a test-prefixed key (`dv_test_sk_*`) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.
</ParamField>

<RequestExample>
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X POST "https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/codes" \
      -H "X-API-Key: dv_live_sk_your_key_here" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```

    ```typescript Node.js theme={null}
    import { Orbit } from '@devotel-orbit/node'

    const orbit = new Orbit({
      apiKey: process.env.ORBIT_API_KEY!,
    })

    const res = await fetch('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/codes', {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.ORBIT_API_KEY!,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({}),
    })
    console.log(await res.json())
    ```

    ```python Python theme={null}
    import os, requests

    headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
    headers["Content-Type"] = "application/json"
    r = requests.post("https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/codes", headers=headers, json={})
    print(r.json())
    ```

    ```go Go theme={null}
    package main

    import (
    	"bytes"
    	"net/http"
    	"os"
    )

    func main() {
    	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/codes", bytes.NewBuffer([]byte(`{}`)))
    	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
    	req.Header.Set("Content-Type", "application/json")
    	http.DefaultClient.Do(req)
    }
    ```

    ```ruby Ruby theme={null}
    require 'net/http'
    require 'json'

    uri = URI('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/codes')
    req = Net::HTTP::Post.new(uri)
    req['X-API-Key'] = ENV['ORBIT_API_KEY']
    req['Content-Type'] = 'application/json'
    req.body = {}.to_json
    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
    puts res.body
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/codes');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-Key: ' . getenv('ORBIT_API_KEY'),
      'Content-Type: application/json',
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
    {}
    JSON);
    echo curl_exec($ch);
    ```
  </CodeGroup>
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {},
    "meta": {
      "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
      "timestamp": "2026-08-26T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

***

### Pay a referral reward

<Note>
  `POST /api/v1/referrals/programs/{id}/conversions/{conversionId}/pay`
</Note>

Mark a pending conversion as paid and fulfill its reward. The update is scoped by the program id, so a conversion from another program is never paid through this endpoint — a `404` is returned instead. For `credit` programs the reward pays into your wallet balance; for `discount_code` programs a redeemable code is minted and returned; for `custom` programs a tracked payout is recorded. The returned conversion carries a `fulfillments` array with each reward's provider and delivery status. Requires the owner, admin, or developer role.

<ParamField path="id" type="string" required>
  —
</ParamField>

<ParamField path="conversionId" type="string" required>
  —
</ParamField>

<ParamField header="Idempotency-Key" type="string">
  Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the `Idempotency-Replay: true` response header.
</ParamField>

<ParamField header="X-Test-Mode" type="string (enum: true|false)">
  Sandbox opt-in for Clerk-session-authenticated requests. Set to `true` to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response `meta.test_mode: true`. **Ignored for live API keys (`dv_live_sk_*`)** — server-to-server clients must use a test-prefixed key (`dv_test_sk_*`) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.
</ParamField>

<RequestExample>
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X POST "https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/conversions/{conversionId}/pay" \
      -H "X-API-Key: dv_live_sk_your_key_here" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```

    ```typescript Node.js theme={null}
    import { Orbit } from '@devotel-orbit/node'

    const orbit = new Orbit({
      apiKey: process.env.ORBIT_API_KEY!,
    })

    const res = await fetch('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/conversions/{conversionId}/pay', {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.ORBIT_API_KEY!,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({}),
    })
    console.log(await res.json())
    ```

    ```python Python theme={null}
    import os, requests

    headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
    headers["Content-Type"] = "application/json"
    r = requests.post("https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/conversions/{conversionId}/pay", headers=headers, json={})
    print(r.json())
    ```

    ```go Go theme={null}
    package main

    import (
    	"bytes"
    	"net/http"
    	"os"
    )

    func main() {
    	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/conversions/{conversionId}/pay", bytes.NewBuffer([]byte(`{}`)))
    	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
    	req.Header.Set("Content-Type", "application/json")
    	http.DefaultClient.Do(req)
    }
    ```

    ```ruby Ruby theme={null}
    require 'net/http'
    require 'json'

    uri = URI('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/conversions/{conversionId}/pay')
    req = Net::HTTP::Post.new(uri)
    req['X-API-Key'] = ENV['ORBIT_API_KEY']
    req['Content-Type'] = 'application/json'
    req.body = {}.to_json
    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
    puts res.body
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/conversions/{conversionId}/pay');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-Key: ' . getenv('ORBIT_API_KEY'),
      'Content-Type: application/json',
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
    {}
    JSON);
    echo curl_exec($ch);
    ```
  </CodeGroup>
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {},
    "meta": {
      "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
      "timestamp": "2026-08-26T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

***

### Update a referral program

<Note>
  `PUT /api/v1/referrals/programs/{id}`
</Note>

Update a referral program by id. The body is a partial program — send only the fields you want to change (`name`, `reward_type`, `reward_value`, per-side reward configs, `enabled`, `target_url`, `start_at`, `end_at`). Returns the updated program, or `404` when no program with that id exists. Requires the owner, admin, or developer role.

<ParamField path="id" type="string" required>
  —
</ParamField>

<ParamField header="Idempotency-Key" type="string">
  Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the `Idempotency-Replay: true` response header.
</ParamField>

<ParamField header="X-Test-Mode" type="string (enum: true|false)">
  Sandbox opt-in for Clerk-session-authenticated requests. Set to `true` to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response `meta.test_mode: true`. **Ignored for live API keys (`dv_live_sk_*`)** — server-to-server clients must use a test-prefixed key (`dv_test_sk_*`) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.
</ParamField>

<RequestExample>
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X PUT "https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
      -H "X-API-Key: dv_live_sk_your_key_here" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```

    ```typescript Node.js theme={null}
    import { Orbit } from '@devotel-orbit/node'

    const orbit = new Orbit({
      apiKey: process.env.ORBIT_API_KEY!,
    })

    const res = await fetch('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
      method: 'PUT',
      headers: {
        'X-API-Key': process.env.ORBIT_API_KEY!,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({}),
    })
    console.log(await res.json())
    ```

    ```python Python theme={null}
    import os, requests

    headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
    headers["Content-Type"] = "application/json"
    r = requests.put("https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers, json={})
    print(r.json())
    ```

    ```go Go theme={null}
    package main

    import (
    	"bytes"
    	"net/http"
    	"os"
    )

    func main() {
    	req, _ := http.NewRequest("PUT", "https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", bytes.NewBuffer([]byte(`{}`)))
    	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
    	req.Header.Set("Content-Type", "application/json")
    	http.DefaultClient.Do(req)
    }
    ```

    ```ruby Ruby theme={null}
    require 'net/http'
    require 'json'

    uri = URI('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
    req = Net::HTTP::Put.new(uri)
    req['X-API-Key'] = ENV['ORBIT_API_KEY']
    req['Content-Type'] = 'application/json'
    req.body = {}.to_json
    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
    puts res.body
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-Key: ' . getenv('ORBIT_API_KEY'),
      'Content-Type: application/json',
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
    {}
    JSON);
    echo curl_exec($ch);
    ```
  </CodeGroup>
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {},
    "meta": {
      "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
      "timestamp": "2026-08-26T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

***

### Delete a referral program

<Note>
  `DELETE /api/v1/referrals/programs/{id}`
</Note>

Delete a referral program by id, removing its issued referral codes and recorded conversions. Returns `204` on success and `404` when no program with that id exists. Requires the owner, admin, or developer role.

<ParamField path="id" type="string" required>
  —
</ParamField>

<ParamField header="X-Test-Mode" type="string (enum: true|false)">
  Sandbox opt-in for Clerk-session-authenticated requests. Set to `true` to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response `meta.test_mode: true`. **Ignored for live API keys (`dv_live_sk_*`)** — server-to-server clients must use a test-prefixed key (`dv_test_sk_*`) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.
</ParamField>

<RequestExample>
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X DELETE "https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
      -H "X-API-Key: dv_live_sk_your_key_here" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```

    ```typescript Node.js theme={null}
    import { Orbit } from '@devotel-orbit/node'

    const orbit = new Orbit({
      apiKey: process.env.ORBIT_API_KEY!,
    })

    const res = await fetch('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
      method: 'DELETE',
      headers: {
        'X-API-Key': process.env.ORBIT_API_KEY!,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({}),
    })
    console.log(await res.json())
    ```

    ```python Python theme={null}
    import os, requests

    headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
    headers["Content-Type"] = "application/json"
    r = requests.delete("https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers, json={})
    print(r.json())
    ```

    ```go Go theme={null}
    package main

    import (
    	"bytes"
    	"net/http"
    	"os"
    )

    func main() {
    	req, _ := http.NewRequest("DELETE", "https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", bytes.NewBuffer([]byte(`{}`)))
    	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
    	req.Header.Set("Content-Type", "application/json")
    	http.DefaultClient.Do(req)
    }
    ```

    ```ruby Ruby theme={null}
    require 'net/http'
    require 'json'

    uri = URI('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
    req = Net::HTTP::Delete.new(uri)
    req['X-API-Key'] = ENV['ORBIT_API_KEY']
    req['Content-Type'] = 'application/json'
    req.body = {}.to_json
    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
    puts res.body
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init('https://api.orbit.devotel.io/api/v1/referrals/programs/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-Key: ' . getenv('ORBIT_API_KEY'),
      'Content-Type: application/json',
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
    {}
    JSON);
    echo curl_exec($ch);
    ```
  </CodeGroup>
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {
      "ok": true
    },
    "meta": {
      "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
      "timestamp": "2026-08-26T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

***