Skip to main content
GET
/
referrals
/
businesses
/
leaderboard
Retrieve the business referral leaderboard
curl --request GET \
  --url https://{defaultHost}/referrals/businesses/leaderboard \
  --header 'Authorization: Bearer <token>'
{
  "leaders": [
    {
      "rank": 123,
      "total_earnings_usd": "<string>",
      "total_volume_usd": "<string>",
      "first_referral_started_at": "2023-11-07T05:31:56Z",
      "user": {
        "id": "<string>",
        "name": "<string>",
        "username": "<string>",
        "profile_picture": {
          "url": "<string>"
        },
        "country": "<string>",
        "city": "<string>"
      }
    }
  ],
  "me": {
    "rank": 123,
    "total_earnings_usd": "<string>",
    "total_volume_usd": "<string>",
    "first_referral_started_at": "2023-11-07T05:31:56Z",
    "user": {
      "id": "<string>",
      "name": "<string>",
      "username": "<string>",
      "profile_picture": {
        "url": "<string>"
      },
      "country": "<string>",
      "city": "<string>"
    }
  }
}

Authorizations

​
Authorization
string
header
required

An account API key, account scoped JWT, app API key, or user OAuth token.

Headers

​
Api-Version-Date
string<date>

Pins the request to a dated API version.

Example:

"2026-07-01"

Query Parameters

​
period
enum<string>
default:all_time

Time window for the rankings. day, month, and year count earnings since the start of the current calendar day, month, or year; all_time ranks lifetime earnings.

Available options:
day,
month,
year,
all_time

Response

caller has no referral earnings

​
leaders
object[]
required

The top referrers by total earnings, best first.

Maximum array length: 10
​
me
object | null
required

The caller's own standing; null when the caller has no referral earnings.