Referrals

Manage your referral code, track referral stats, and claim rewards. Share your referral code with others to earn bonus queries for both you and the person you refer.

tip

Try this endpoint live in the API Playground.

How It Works

1. Get your referral code — Each user gets a unique code (e.g., CDB-A1B2C3D4)
2. Share it — Send the signup link https://app.crondb.com/signup?ref=YOUR_CODE to others
3. They sign up — When someone registers using your code, the referral is tracked
4. Both earn rewards — Referrer gets 500 bonus queries, referee gets 200 bonus queries
5. Hit milestones — Earn additional bonuses at 5, 10, 25, and 50 successful referrals

Milestone Bonuses

Referrals	Bonus Queries
5	1,000
10	2,500
25	5,000
50	10,000

Maximum referrals per user: 50.

Endpoints

Method	Endpoint	Auth	Description
GET	/v1/referrals/code	Required	Get your referral code
GET	/v1/referrals/stats	Required	Referral stats and earnings
GET	/v1/referrals/history	Required	Referral history
POST	/v1/referrals/validate/{code}	None	Validate a referral code
POST	/v1/referrals/claim	Required	Claim referral rewards
GET	/v1/referrals/leaderboard	None	Top referrers

---

Get Referral Code

Returns your unique referral code. Generates one automatically if you don't have one yet.

GET /v1/referrals/code

cURL

curl -H "Authorization: Bearer cdb_your_api_key_here" \
  "https://api.crondb.com/v1/referrals/code"

Python

import requests

response = requests.get(
    "https://api.crondb.com/v1/referrals/code",
    headers={"Authorization": "Bearer cdb_your_api_key_here"},
)
print(response.json())

Node.js

const response = await fetch("https://api.crondb.com/v1/referrals/code", {
  headers: { Authorization: "Bearer cdb_your_api_key_here" },
});
const data = await response.json();
console.log(data.referral_code);

Response

{
  "referral_code": "CDB-A1B2C3D4"
}

Field	Type	Description
referral_code	string	Your unique referral code (format: CDB-XXXXXXXX)

---

Referral Stats

Get your referral program statistics including total invites, conversions, and earnings.

GET /v1/referrals/stats

curl -H "Authorization: Bearer cdb_your_api_key_here" \
  "https://api.crondb.com/v1/referrals/stats"

Response

{
  "total_invites": 12,
  "successful_signups": 8,
  "rewards_claimed": 6,
  "queries_earned": 4000,
  "max_referrals": 50,
  "next_milestone": 10,
  "next_milestone_bonus": 2500
}

Field	Type	Description
total_invites	integer	Total people who used your referral code
successful_signups	integer	People who completed signup
rewards_claimed	integer	Referrals where rewards have been claimed
queries_earned	integer	Total bonus queries earned (including milestones)
max_referrals	integer	Maximum referrals allowed (50)
next_milestone	integer | null	Next milestone target, or null if all achieved
next_milestone_bonus	integer | null	Bonus queries at next milestone

---

Referral History

List all your referrals with their status and timestamps.

GET /v1/referrals/history

curl -H "Authorization: Bearer cdb_your_api_key_here" \
  "https://api.crondb.com/v1/referrals/history"

Response

[
  {
    "id": 42,
    "referee_email": "j***n@gmail.com",
    "status": "rewarded",
    "reward_given": true,
    "created_at": "2026-03-15 10:30:00",
    "completed_at": "2026-03-16 14:22:00"
  },
  {
    "id": 38,
    "referee_email": "a***x@company.io",
    "status": "completed",
    "reward_given": false,
    "created_at": "2026-03-10 09:15:00",
    "completed_at": "2026-03-12 11:05:00"
  }
]

Field	Type	Description
id	integer	Referral ID
referee_email	string | null	Masked email of the referred user
status	string	"pending", "completed", or "rewarded"
reward_given	boolean	Whether the referrer bonus was applied
created_at	string | null	When the referral was created
completed_at	string | null	When the referee completed signup

---

Validate Referral Code

Check if a referral code is valid. This is a public endpoint used during signup — no authentication required.

POST /v1/referrals/validate/{code}

curl -X POST "https://api.crondb.com/v1/referrals/validate/CDB-A1B2C3D4"

Response — Valid Code

{
  "valid": true,
  "referrer_email": "j***n@gmail.com"
}

Response — Invalid Code

{
  "valid": false,
  "referrer_email": null
}

Field	Type	Description
valid	boolean	Whether the code exists and is still usable
referrer_email	string | null	Masked email of the referrer (only if valid)

A code is invalid if it doesn't exist or the referrer has reached the 50-referral maximum.

---

Claim Reward

Claim your referral reward as a referee. Call this after signing up with a referral code and making your first query.

POST /v1/referrals/claim

curl -X POST \
  -H "Authorization: Bearer cdb_your_api_key_here" \
  "https://api.crondb.com/v1/referrals/claim"

Response — Success

{
  "queries_awarded": 200,
  "message": "You earned 200 bonus queries!"
}

Error Responses

Status	Detail	Reason
404	No claimable referral found	No completed referral exists for this user, or already claimed

---

Leaderboard

Get the top 10 referrers (anonymized). This is a public endpoint — no authentication required.

GET /v1/referrals/leaderboard

curl "https://api.crondb.com/v1/referrals/leaderboard"

Response

[
  { "rank": 1, "name": "J***n", "referrals": 23 },
  { "rank": 2, "name": "S***a", "referrals": 18 },
  { "rank": 3, "name": "M***k", "referrals": 12 }
]

Field	Type	Description
rank	integer	Position on the leaderboard
name	string	Anonymized name from the referrer's email
referrals	integer	Number of completed referrals

---

Error Responses

All authenticated endpoints return standard error responses:

Status	Detail	Reason
401	Not authenticated	Missing or invalid Bearer token
403	Forbidden	Insufficient permissions

Next Steps

• Usage & Rate Limits — View your plan and credits
• Authentication — Manage your API keys