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

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

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

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

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. For the read side of the loop with full response bodies (the redirect’s 302, a pending conversion, a leaderboard row, and a paid payout), follow the referral conversion loop walkthrough. 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

Node uses the typed orbit.referrals.* helpers; Python reaches the same endpoints through the generic client.request() escape hatch; Go, Ruby, and PHP use plain HTTP clients (no SDK dependency) against the same endpoints:

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":"September referral push","referrer_credit_cents":1000,"referee_credit_cents":500,"conversion_window_days":30}'

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

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

// Create a program, then read its leaderboard + conversions
const program = await orbit.referrals.createProgram({
  name: "September referral push",
  referrer_credit_cents: 1_000,
  referee_credit_cents: 500,
  conversion_window_days: 30,
  per_referrer_cap: 50,
});
const programId = program.data.id;

const board = await orbit.referrals.leaderboard(programId, { limit: 10 });
console.log(board.data[0]?.referrer_id, board.data[0]?.credits_earned_cents);

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

program = client.request("POST", "/referrals/programs", json_body={
    "name": "September referral push",
    "referrer_credit_cents": 1000,
    "referee_credit_cents": 500,
    "conversion_window_days": 30,
})
program_id = program["data"]["id"]
board = client.request("GET", f"/referrals/programs/{program_id}/leaderboard")

package main

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

func main() {
	body := []byte(`{"name":"September referral push","referrer_credit_cents":1000,"referee_credit_cents":500,"conversion_window_days":30}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/referrals/programs", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status)
}

require 'net/http'

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 = '{"name":"September referral push","referrer_credit_cents":1000,"referee_credit_cents":500,"conversion_window_days":30}'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/referrals/programs');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"September referral push","referrer_credit_cents":1000,"referee_credit_cents":500,"conversion_window_days":30}');
echo curl_exec($ch);

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

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

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

const program = await orbit.referrals.createProgram({
  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",
});

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

program = client.request("POST", "/referrals/programs", json_body={
    "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",
})

package main

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

func main() {
	body := []byte(`{"name":"Q3 customer referral","reward_type":"discount_code","reward_value":"20% off next month","target_url":"https://your-product.example/signup"}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/referrals/programs", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status)
}

require 'net/http'

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 = '{"name":"Q3 customer referral","reward_type":"discount_code","reward_value":"20% off next month","target_url":"https://your-product.example/signup"}'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/referrals/programs');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"Q3 customer referral","reward_type":"discount_code","reward_value":"20% off next month","target_url":"https://your-product.example/signup"}');
echo curl_exec($ch);

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

List programs

GET /api/v1/referrals/programs Returns every program in your workspace, including disabled ones.

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

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

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

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

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

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

package main

import (
	"fmt"
	"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"))
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status)
}

require 'net/http'

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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/referrals/programs');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

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

{
  "data": [
    {
      "id": "rpg_9f8a7b6c5d4e3f2a1b0c",
      "name": "Q3 customer referral",
      "reward_type": "discount_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_list_001",
    "timestamp": "2026-08-25T10:01:00Z"
  }
}

Get a program

GET /api/v1/referrals/programs/{id} Fetches one program by id. Returns 404 when no program with that id exists in your workspace.

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

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

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

const program = await orbit.referrals.getProgram("rpg_9f8a7b6c5d4e3f2a1b0c");

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

program = client.request("GET", "/referrals/programs/rpg_9f8a7b6c5d4e3f2a1b0c")

package main

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

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

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_9f8a7b6c5d4e3f2a1b0c')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_9f8a7b6c5d4e3f2a1b0c');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

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

{
  "data": {
    "id": "rpg_9f8a7b6c5d4e3f2a1b0c",
    "name": "Q3 customer referral",
    "reward_type": "discount_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_get_001",
    "timestamp": "2026-08-25T10:01:00Z"
  }
}

Update a program

PUT /api/v1/referrals/programs/{id} Update any field with 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.

curl -X PUT "https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_9f8a7b6c5d4e3f2a1b0c" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false, "end_at": "2026-10-31T23:59:59Z" }'

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

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

const program = await orbit.referrals.updateProgram("rpg_9f8a7b6c5d4e3f2a1b0c", {
  enabled: false,
  end_at: "2026-10-31T23:59:59Z",
});

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

program = client.request("PUT", "/referrals/programs/rpg_9f8a7b6c5d4e3f2a1b0c", json_body={
    "enabled": False,
    "end_at": "2026-10-31T23:59:59Z",
})

package main

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

func main() {
	body := []byte(`{"enabled":false,"end_at":"2026-10-31T23:59:59Z"}`)
	req, _ := http.NewRequest("PUT", "https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_9f8a7b6c5d4e3f2a1b0c", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status)
}

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_9f8a7b6c5d4e3f2a1b0c')
req = Net::HTTP::Put.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = '{"enabled":false,"end_at":"2026-10-31T23:59:59Z"}'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_9f8a7b6c5d4e3f2a1b0c');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"enabled":false,"end_at":"2026-10-31T23:59:59Z"}');
echo curl_exec($ch);

curl -X PUT "https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_9f8a7b6c5d4e3f2a1b0c" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false, "end_at": "2026-10-31T23:59:59Z" }'

{
  "data": {
    "id": "rpg_9f8a7b6c5d4e3f2a1b0c",
    "name": "Q3 customer referral",
    "reward_type": "discount_code",
    "enabled": false,
    "target_url": "https://your-product.example/signup",
    "end_at": "2026-10-31T23:59:59Z",
    "created_at": "2026-08-25T10:00:00Z"
  },
  "meta": {
    "request_id": "req_prog_upd_001",
    "timestamp": "2026-08-25T10:02:00Z"
  }
}

Delete a program

DELETE /api/v1/referrals/programs/{id} Cascade-removes the program’s codes and conversions. Responds 204 No Content; 404 when no program with that id exists.

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

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

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

await orbit.referrals.deleteProgram("rpg_9f8a7b6c5d4e3f2a1b0c");

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

client.request("DELETE", "/referrals/programs/rpg_9f8a7b6c5d4e3f2a1b0c")

package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_9f8a7b6c5d4e3f2a1b0c", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status)
}

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_9f8a7b6c5d4e3f2a1b0c')
req = Net::HTTP::Delete.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.code

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/referrals/programs/rpg_9f8a7b6c5d4e3f2a1b0c');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

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

A 204 No Content operation says so inline — the response body is empty.

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

List programs

Get a program

Update a program

Delete 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

​List programs

​Get a program

​Update a program

​Delete 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

List programs

Get a program

Update a program

Delete a program

Codes & conversions

Issue a per-referrer code

Read the leaderboard

Pay a conversion

See also