Referrals API

Referral programs that Orbit customers run for their end-users — not Orbit’s own referral program. Define a program, issue per-user referral codes, track conversions, run a leaderboard, and approve payouts. Base path: /api/v1/referrals Authentication: API key (X-API-Key) or session JWT. Program create, update, delete, code issuance, and payout approval require the owner, admin, or developer role; reads only need authentication.

Using the SDKs

import { Orbit } from "@devotel-orbit/node";

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

const res = await orbit.referrals.listPrograms();

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/referrals")

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

Programs

Method	Path	Purpose
`POST`	`/api/v1/referrals/programs`	Create a referral program
`GET`	`/api/v1/referrals/programs`	List programs
`GET`	`/api/v1/referrals/programs/{id}`	Get a program
`PUT`	`/api/v1/referrals/programs/{id}`	Update reward and expiration
`DELETE`	`/api/v1/referrals/programs/{id}`	Delete a program

Create a program

POST /api/v1/referrals/programs Creates the program enabled unless you pass enabled: false. reward_type is:

credit — paid into your wallet balance when you mark a conversion paid.
discount_code — a redeemable code minted and returned on payout.
custom — a payout record you fulfill yourself.

curl -X POST "https://api.orbit.devotel.io/api/v1/referrals/programs" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 customer referral",
    "reward_type": "discount_code",
    "reward_value": "20% off next month",
    "referrer_reward": { "amount": 20, "providerId": "orbit_code" },
    "referee_reward": { "amount": 10, "providerId": "orbit_code" },
    "target_url": "https://your-product.example/signup",
    "start_at": "2026-09-01T00:00:00Z",
    "end_at": "2026-09-30T23:59:59Z"
  }'

The referrer_reward and referee_reward blocks carry amount (minor units for credit, percentage for discount_code), an optional 3-letter currency, an optional providerId to pin a fulfillment provider, and freeform metadata. Omit referee_reward for a single-sided program.

{
  "data": {
    "id": "rpg_9f8a7b6c5d4e3f2a1b0c",
    "name": "Q3 customer referral",
    "reward_type": "discount_code",
    "reward_value": "20% off next month",
    "referrer_reward": { "amount": 20, "providerId": "orbit_code" },
    "referee_reward": { "amount": 10, "providerId": "orbit_code" },
    "enabled": true,
    "target_url": "https://your-product.example/signup",
    "start_at": "2026-09-01T00:00:00Z",
    "end_at": "2026-09-30T23:59:59Z",
    "created_at": "2026-08-25T10:00:00Z"
  },
  "meta": {
    "request_id": "req_prog_001",
    "timestamp": "2026-08-25T10:00:00Z"
  }
}

Update any field with PUT /api/v1/referrals/programs/{id} using a partial body — send only what changes. Deleting a program cascade-removes its codes and conversions; prefer enabled: false when the program might come back.

Codes & conversions

Method	Path	Purpose
`POST`	`/api/v1/referrals/programs/{id}/codes`	Issue a referral code (per referrer)
`GET`	`/api/v1/referrals/programs/{id}/leaderboard`	Top referrers ranked by conversions
`GET`	`/api/v1/referrals/programs/{id}/conversions`	List conversions
`POST`	`/api/v1/referrals/programs/{id}/conversions/{conversionId}/pay`	Approve and mark a conversion as paid

Issue a per-referrer code

POST /api/v1/referrals/programs/{id}/codes The endpoint is mint-or-get: calling it again for the same contact and program returns the existing code instead of a duplicate.

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

{
  "data": {
    "code": "AbCdEf23",
    "contact_id": "con_referrer_abc123",
    "program_id": "rpg_9f8a7b6c5d4e3f2a1b0c",
    "visits": 0,
    "signups": 0,
    "rewards_paid": 0
  },
  "meta": {
    "request_id": "req_code_001",
    "timestamp": "2026-08-25T10:01:00Z"
  }
}

Build the share link from the returned code: https://api.orbit.devotel.io/r/AbCdEf23.

Read the leaderboard

GET /api/v1/referrals/programs/{id}/leaderboard?limit=25

curl "https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_9f8a7b6c5d4e3f2a1b0c/leaderboard?limit=25" \
  -H "X-API-Key: $ORBIT_API_KEY"

Each row is a referrer code with its counters and the referrer label. limit defaults to 25 and maxes at 100 — for program-wide aggregates use the totals endpoint (documented in the Referral programs guide), not a sum over the leaderboard page.

{
  "data": [
    {
      "referrer_contact_id": "con_referrer_abc123",
      "referrer_name": "Ada Lovelace",
      "code": "AbCdEf23",
      "visits": 148,
      "signups": 12,
      "rewards_paid": 9
    },
    {
      "referrer_contact_id": "con_referrer_def456",
      "referrer_name": "Grace Hopper",
      "code": "Gh9Jk02",
      "visits": 96,
      "signups": 7,
      "rewards_paid": 5
    }
  ],
  "meta": {
    "request_id": "req_board_001",
    "timestamp": "2026-08-25T10:02:00Z"
  }
}

Pay a conversion

POST /api/v1/referrals/programs/{id}/conversions/{conversionId}/pay Approve a pending conversion and fulfill the reward. The endpoint is scoped by program id: a conversion that belongs to another program returns 404.

curl -X POST "https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_9f8a7b6c5d4e3f2a1b0c/conversions/rconv_0017b6x5y4z/pay" \
  -H "X-API-Key: $ORBIT_API_KEY"

The response carries the conversion with reward_status: "paid" plus a fulfillments array — one entry per rewarded side with its provider and delivery status. For discount_code programs the fulfillment includes the minted redeemable code the referrer receives.

{
  "data": {
    "id": "rconv_0017b6x5y4z",
    "program_id": "rpg_9f8a7b6c5d4e3f2a1b0c",
    "referrer_contact_id": "con_referrer_abc123",
    "referee_contact_id": "con_referee_zzz987",
    "reward_status": "paid",
    "reject_reason": null,
    "fulfillments": [
      {
        "id": "incf_01x9v2",
        "providerId": "orbit_code",
        "status": "delivered",
        "recipientContactId": "con_referrer_abc123",
        "code": "Q3-A7F2-9KQZ"
      }
    ]
  },
  "meta": {
    "request_id": "req_pay_001",
    "timestamp": "2026-08-25T10:03:00Z"
  }
}

The customer-facing redirect at /r/:code is mounted at the API root (no /api prefix) so referral links can be branded short URLs. It’s not authenticated — on each click it records the visit, sets an attribution cookie, and redirects to the program’s target_url with ?ref_code=<code> appended.

API Reference

All Endpoints

Run referral programs, issue codes, and pay rewards

Referrals API

Using the SDKs

Programs

Create a program

Codes & conversions

Issue a per-referrer code

Read the leaderboard

Pay a conversion

See also

​Referrals API

​Using the SDKs

​Programs

​Create a program

​Codes & conversions

​Issue a per-referrer code

​Read the leaderboard

​Pay a conversion

​See also

Referrals API

Using the SDKs

Programs

Create a program

Codes & conversions

Issue a per-referrer code

Read the leaderboard

Pay a conversion

See also