Referral System

The referral system allows you to invite others to join the platform using a unique referral code. When someone registers using your code, you earn points. This guide covers how to create and retrieve your referral code.

Overview

The referral system provides a way to grow the platform community while rewarding users:

Unique Referral Code - Each user gets a unique code to share
Points Reward - Earn 1,000 points when you create your referral code
Referral Bonus - Earn 100 points each time someone uses your code
One-Time Creation - Your referral code is created once and remains the same

Prerequisites

Before creating a referral code, ensure you have:

Completed authentication and have a valid access token
Created a nickname (required before creating a referral code)

Get Referral Code

Retrieve your referral code. If you haven't created one yet, this will return a not found error.

Get referral code

curl -X GET https://api.example.com/api/referral \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 200,
  "message": "Referral retrieved successfully",
  "data": {
    "referral": {
      "id": "referral-id",
      "client_id": "client-id",
      "code": "ABC123XYZ",
      "created_at": "2024-01-01T00:00:00.000Z"
    }
  }
}

Response (No referral code):

{
  "status": 404,
  "message": "Referral not found"
}

Create Referral Code

Create a new referral code for your account. You can only create a referral code once. After creation, your code remains the same.

Create referral code

curl -X POST https://api.example.com/api/referral \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 201,
  "message": "Referral created successfully",
  "data": {
    "referral": {
      "id": "referral-id",
      "client_id": "client-id",
      "code": "ABC123XYZ",
      "created_at": "2024-01-01T00:00:00.000Z"
    }
  }
}

Note: Creating a referral code rewards you with 1,000 points in the platform's points system.

How Referrals Work

Create Your Code: Generate your unique referral code
Share Your Code: Share your code with friends, family, or on social media
New User Registers: When someone registers using your code, they must provide it during registration
Earn Points: You earn 100 points each time someone successfully registers with your code

Referral Code Format

Referral codes are alphanumeric strings that are:

Unique - Each code is unique across the platform
Case-Sensitive - Codes are case-sensitive
Alphanumeric - Contains letters and numbers
Fixed Length - Codes have a consistent format

Example: ABC123XYZ

Using a Referral Code

When registering a new account, users can provide a referral code:

curl -X POST https://api.example.com/api/auth/register \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "email": "newuser@example.com",
    "password": "secure-password",
    "termsOfUse": true,
    "privacyPolicy": true
  }' \
  "?referral=ABC123XYZ"

The referral code is passed as a query parameter during registration.

Points Rewards

Creating a Referral Code

Points: 1,000
When: Immediately upon creating your referral code
One-time: Yes

Referring Someone

Points: 100
When: Someone successfully registers using your referral code
Repeatable: Yes (earn 100 points per referral)

Error Handling

Nickname Required

{
  "status": 400,
  "message": "It's necessary to create a nickname first"
}

This error occurs when trying to create a referral code before creating a nickname.

Referral Already Created

{
  "status": 400,
  "message": "Referral already was created",
  "data": {
    "referral": {
      "id": "referral-id",
      "code": "ABC123XYZ"
    }
  }
}

This error occurs when trying to create a referral code but you already have one. Use the get endpoint to retrieve your existing code.

Referral Not Found

{
  "status": 404,
  "message": "Referral not found"
}

This error occurs when trying to retrieve a referral code that doesn't exist. Create one first using the POST endpoint.

Complete Flow Example

Here's a complete example of the referral flow:

# 1. Create nickname (required first)
curl -X POST https://api.example.com/api/nickname \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "nickname": "johndoe"
  }'

# 2. Create referral code
curl -X POST https://api.example.com/api/referral \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 3. Get your referral code
curl -X GET https://api.example.com/api/referral \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 4. Share your code (e.g., ABC123XYZ)
# When someone registers with your code, you'll earn 100 points

Important Notes

Nickname Required: You must create a nickname before you can create a referral code. This ensures that users in the referral system can be properly identified.
One-Time Creation: You can only create a referral code once. After creation, your code remains the same and cannot be changed or regenerated.
Unique Code: Each referral code is unique across the entire platform. No two users will have the same code.
Points Reward: Creating a referral code immediately awards you 1,000 points. Additionally, you earn 100 points each time someone registers using your code.
Code Persistence: Your referral code never expires and remains active as long as your account exists.
Case Sensitivity: Referral codes are case-sensitive. Make sure to share your code exactly as it appears (including capitalization).
Registration Requirement: New users must provide the referral code during registration (as a query parameter) for you to earn points.

Best Practices

Share Widely: Share your referral code on social media, forums, or with friends to maximize your referral points.
Track Your Referrals: Check your points regularly to see how many people have used your code.
Provide Value: Help new users understand the platform to increase the likelihood they'll complete registration and you'll earn points.
Keep It Handy: Save your referral code in an easy-to-access place so you can share it quickly when needed.
Monitor Points: Use the points system to track how many referrals you've made and your ranking position.