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 → then run the enrol → attribute → reward loop end to end. 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 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.

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"
  }
}

Worked sequences — enrol and attribute

The first section reads a program from the outside; this sequence runs one referral the way a signup funnel drives it: mint a code → let the /r/:code redirect do the attribution → page the conversion → pay the reward → replay the enrol safely.

1. Enrol a referrer — mint their code

POST /api/v1/referrals/programs/{id}/codes

Mint a referral code for one of your contacts. The request body is the contact id; the response is the per-contact code row with its live visit, signup, and paid-reward counters. Build the share URL as https://<your-domain>/r/<code> — the unauthenticated /r/:code redirect sets the attribution cookie and appends ?ref_code= to the program’s target_url (or the default signup page when no target is configured).

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_8fb2d1b7c00c4ec9/codes" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": "cnt_8fb2d1b7c00c4ec9"}'

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

201

{
  "data": {
    "id": "rcode_3c9a71f2e0b84d6a",
    "program_id": "rpg_8fb2d1b7c00c4ec9",
    "contact_id": "cnt_8fb2d1b7c00c4ec9",
    "code": "ref_abc123",
    "visits": 0,
    "signups": 0,
    "rewards_paid": 0,
    "created_at": "2026-08-26T12:05:11.241Z"
  },
  "meta": {
    "request_id": "req_rpg_code_issue",
    "timestamp": "2026-08-26T12:05:11.318Z"
  }
}

2. Replay the enrol — the same code comes back

POST /api/v1/referrals/programs/{id}/codes

The enrol op is mint-or-get: the program keeps one code per (program_id, contact_id) pair, so retrying the same enrol — a client timeout retry, or a signup form submitted twice — returns that contact’s existing code row instead of minting a duplicate. Safe to call on page load every time your funnel needs the referrer’s share URL.

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_8fb2d1b7c00c4ec9/codes" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": "cnt_8fb2d1b7c00c4ec9"}'

// Retry-safe: replaying the same enrol returns the original code
// with the counters it has accrued so far — never a duplicate.
const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_8fb2d1b7c00c4ec9/codes",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contact_id: "cnt_8fb2d1b7c00c4ec9" }),
  },
);
const { data } = await res.json();
console.log(data.code); // "ref_abc123" — the original code

200 Replay — existing code returned

{
  "data": {
    "id": "rcode_3c9a71f2e0b84d6a",
    "program_id": "rpg_8fb2d1b7c00c4ec9",
    "contact_id": "cnt_8fb2d1b7c00c4ec9",
    "code": "ref_abc123",
    "visits": 2,
    "signups": 0,
    "rewards_paid": 0,
    "created_at": "2026-08-26T12:05:11.241Z"
  },
  "meta": {
    "request_id": "req_rpg_code_replay",
    "timestamp": "2026-08-26T12:05:12.002Z"
  }
}

3. Read per-participant attribution progress

GET /api/v1/referrals/programs/{id}/leaderboard

Every visit and signup the referred traffic produces lands on the code’s counters: the /r/:code redirect increments visits, and a referee signup converts into a signups increment. Re-read the leaderboard to watch one participant climb — each row is a per-participant attribution record (referrer_contact_id + human label + the code’s counters), and conversion rows (next step) give the per-referee detail.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_8fb2d1b7c00c4ec9/leaderboard?limit=10" \
  -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=10",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "leaderboard": [
      {
        "referrer_contact_id": "cnt_8fb2d1b7c00c4ec9",
        "referrer_name": "Maya Patel",
        "code": "ref_abc123",
        "visits": 2,
        "signups": 1,
        "rewards_paid": 0
      }
    ]
  },
  "meta": {
    "request_id": "req_rpg_attr_progress",
    "timestamp": "2026-08-26T12:06:04.000Z"
  }
}

4. Record the conversion — the referee signs up

GET /api/v1/referrals/programs/{id}/conversions

When a referred visitor signs up, Orbit records the conversion itself — the referral of a contact’s signup — tying the referee back to the referrer through the code. There is nothing to POST: page GET /api/v1/referrals/programs/{id}/conversions to see each recorded conversion with both sides’ contact ids, human-readable labels, and the reward status (pending, paid, rejected) with the rejection reason when rejected. Filter with status and page with limit / offset.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_8fb2d1b7c00c4ec9/conversions?status=pending&limit=25" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

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

200

{
  "data": {
    "conversions": [
      {
        "id": "rcnv_9d41c03aa1f24b7e",
        "program_id": "rpg_8fb2d1b7c00c4ec9",
        "referrer_contact_id": "cnt_8fb2d1b7c00c4ec9",
        "referee_contact_id": "cnt_2f7e09b4d5c16a83",
        "referrer_name": "Maya Patel",
        "referee_name": "Jordan Lee",
        "converted_at": "2026-08-26T12:07:44.901Z",
        "rewarded_at": null,
        "reward_status": "pending",
        "reject_reason": null
      }
    ],
    "total": 1,
    "limit": 25,
    "offset": 0
  },
  "meta": {
    "request_id": "req_rpg_conv_list",
    "timestamp": "2026-08-26T12:07:45.120Z"
  }
}

5. Apply the reward per the program’s contract

POST /api/v1/referrals/programs/{id}/conversions/{conversionId}/pay

Approve a pending conversion and fulfill its reward. What the reward delivery does is fixed by the program’s reward_type from step 1 — the pay call follows the program’s own contract, so the same endpoint mints a voucher for discount programs and credits the wallet for credit programs:

credit — the reward pays into your wallet balance.
discount_code — a unique redeemable code (voucher) is minted and returned.
custom — a tracked payout is recorded.

The conversion must belong to the program in the path — pay is scoped by the program id, so a conversion from another program is a 404, never a cross-program payout. The returned conversion carries reward_status: "paid", the rewarded_at stamp, and a fulfillments array with each reward’s provider and delivery status.

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_8fb2d1b7c00c4ec9/conversions/rcnv_9d41c03aa1f24b7e/pay" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

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

200

{
  "data": {
    "id": "rcnv_9d41c03aa1f24b7e",
    "program_id": "rpg_8fb2d1b7c00c4ec9",
    "referrer_contact_id": "cnt_8fb2d1b7c00c4ec9",
    "referee_contact_id": "cnt_2f7e09b4d5c16a83",
    "converted_at": "2026-08-26T12:07:44.901Z",
    "rewarded_at": "2026-08-26T12:09:02.400Z",
    "reward_status": "paid",
    "reject_reason": null,
    "fulfillments": [
      {
        "id": "rful_5b2e8d01c9a44f70",
        "provider": "wallet_credit",
        "status": "delivered",
        "recipient_contact_id": "cnt_8fb2d1b7c00c4ec9"
      }
    ]
  },
  "meta": {
    "request_id": "req_rpg_reward_pay",
    "timestamp": "2026-08-26T12:09:02.501Z"
  }
}

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

Worked sequences — enrol and attribute

1. Enrol a referrer — mint their code

2. Replay the enrol — the same code comes back

3. Read per-participant attribution progress

4. Record the conversion — the referee signs up

5. Apply the reward per the program’s contract

Errors

​Worked referrals samples

​1. List referral programs

​2. Read the program leaderboard

​3. Read program-wide totals

​Worked sequences — enrol and attribute

​1. Enrol a referrer — mint their code

​2. Replay the enrol — the same code comes back

​3. Read per-participant attribution progress

​4. Record the conversion — the referee signs up

​5. Apply the reward per the program’s contract

​Errors

Worked referrals samples

1. List referral programs

2. Read the program leaderboard

3. Read program-wide totals

Worked sequences — enrol and attribute

1. Enrol a referrer — mint their code

2. Replay the enrol — the same code comes back

3. Read per-participant attribution progress

4. Record the conversion — the referee signs up

5. Apply the reward per the program’s contract

Errors