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

> Referral programs Orbit customers run for **their own** end-users — issue codes, track conversions, run a leaderboard, pay out rewards.

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

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

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

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.