Create Referral

Create a new referral when someone signs up via a referral link. This endpoint is typically called when a user completes signup after scanning a QR code from an ambassador poster.

Overview

The Create Referral endpoint allows you to register a new referral signup in your system. This is a critical endpoint that links:

The impression (QR scan) that initiated the referral
The person who signed up (referral)
The student ambassador who generated the referral
The program the referral belongs to

Use this endpoint to:

Register new signups from referral links
Track the conversion funnel from QR scan to signup
Associate referrals with their originating impressions
Enable commission tracking for ambassadors

Authentication

This endpoint requires authentication using a Bearer token in the Authorization header:

Authorization: Bearer sk_your_secret_key_here

Request Body

impression_id

string

required

Required. The ID of the impression (QR scan) that led to this referral. This links the referral back to the original QR code scan and poster placement.Example: imp_123abcNote: The impression must exist in your system before creating a referral.

first_name

string

required

Required. First name of the person who signed up via the referral link.Example: John

last_name

string

required

Required. Last name of the person who signed up via the referral link.Example: Doe

string

required

Required. Email address of the referred person. This should be a valid email address and is used for communication and verification.Example: john.doe@example.com

profile_picture

string

Optional URL to the profile picture of the referred person. This can be used to display avatars in dashboards.Example: https://example.com/profiles/john-doe.jpg

metadata

object

Optional additional metadata about the referral. Use this to store custom information like signup source, marketing campaign, or other relevant data.Example:

{
  "source": "poster_qr_code",
  "location": "campus_center",
  "campaign": "spring_2024"
}

idempotency_key

string

Optional unique key for idempotent requests. If you send the same idempotency_key within a short time window, the API will return the same referral instead of creating a duplicate. This is useful for retry logic.Example: idemp_20240115_123456Best Practice: Use a combination of timestamp and unique identifier to ensure uniqueness.

Request Example

curl -X POST "http://localhost:3000/api/v1/referrals" \
  -H "Authorization: Bearer sk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "impression_id": "imp_123abc",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "profile_picture": "https://example.com/profiles/john-doe.jpg",
    "metadata": {
      "source": "poster_qr_code",
      "location": "campus_center"
    },
    "idempotency_key": "ref_20240115_123456"
  }'

Response

On success, the API returns the created referral object:

string

required

Unique identifier for the newly created referral.

impression_id

string

required

The impression ID that was provided in the request.

first_name

string

required

First name of the referral.

last_name

string

required

Last name of the referral.

string

required

Email address of the referral.

status

string

required

Initial status of the referral, typically pending.

program_id

string

required

ID of the program, automatically determined from the impression.

student_id

string

required

ID of the student ambassador, automatically determined from the impression.

created_at

string

required

ISO 8601 timestamp of when the referral was created.

Response Example

{
  "id": "ref_789ghi",
  "impression_id": "imp_123abc",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "profile_picture": "https://example.com/profiles/john-doe.jpg",
  "status": "pending",
  "program_id": "prog_123abc",
  "student_id": "user_123abc",
  "created_at": "2024-01-15T10:30:00Z",
  "metadata": {
    "source": "poster_qr_code",
    "location": "campus_center"
  }
}

Error Responses

400

object

Bad Request - Invalid request data

{
  "error": "Bad Request",
  "message": "Missing required field: impression_id"
}

Common causes:

Missing required fields
Invalid email format
Invalid impression_id (impression doesn’t exist)

401

object

Unauthorized - Invalid or missing API key

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

Use Cases

When a user signs up via a referral link, create the referral:

async function handleSignupWebhook(signupData, impressionId) {
  try {
    const response = await fetch('http://localhost:3000/api/v1/referrals', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        impression_id: impressionId,
        first_name: signupData.firstName,
        last_name: signupData.lastName,
        email: signupData.email,
        profile_picture: signupData.profilePicture,
        metadata: {
          source: 'web_signup',
          signup_method: 'email'
        },
        idempotency_key: `signup_${signupData.userId}_${Date.now()}`
      })
    });
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message);
    }
    
    const referral = await response.json();
    console.log('Referral created:', referral.id);
    return referral;
  } catch (error) {
    console.error('Error creating referral:', error);
    throw error;
  }
}

Idempotent Referral Creation

Use idempotency keys to prevent duplicate referrals:

async function createReferralSafely(referralData, userId) {
  const idempotencyKey = `ref_${userId}_${referralData.impression_id}`;
  
  const response = await fetch('http://localhost:3000/api/v1/referrals', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      ...referralData,
      idempotency_key: idempotencyKey
    })
  });
  
  // If the referral already exists (idempotent), the API returns the existing one
  return await response.json();
}

Batch Referral Creation

Create multiple referrals in sequence:

async function createReferralsBatch(referralsData) {
  const results = [];
  
  for (const referralData of referralsData) {
    try {
      const referral = await createReferralSafely(referralData, referralData.userId);
      results.push({ success: true, referral });
    } catch (error) {
      results.push({ success: false, error: error.message });
    }
  }
  
  return results;
}

Best Practices

Always use idempotency keys - Prevents duplicate referrals if your request is retried
Validate impression_id - Ensure the impression exists before creating the referral
Store metadata - Use the metadata field to track useful information for analytics
Handle errors gracefully - Check for 400 errors and provide user-friendly messages
Verify email format - Validate email addresses before sending to the API
Link to impressions - Always provide a valid impression_id to maintain the referral chain

Workflow

The typical referral creation workflow:

User scans QR code → Impression created
User clicks through and signs up → Referral created (this endpoint)
User makes a purchase → Earning created (see Earnings API)
Referral status updated to converted

Rate Limits

This endpoint is subject to rate limiting. Check response headers for rate limit information.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

impression_id

string

required

The impression (QR scan) ID that led to this referral

first_name

string

required

last_name

string

required

string

required

profile_picture

string

URL to profile picture

metadata

object

Additional metadata about the referral

idempotency_key

string

A unique key for idempotent requests

Response

Referral created successfully

API Documentation

Users

Referrals

Posters

Impressions

Earnings

Create Referral

Overview

Authentication

Request Body

Request Example

Response

Response Example

Error Responses

Use Cases

Idempotent Referral Creation

Batch Referral Creation

Best Practices

Workflow

Rate Limits

Authorizations

Body

Response

API Documentation

Users

Referrals

Posters

Impressions

Earnings

​Overview

​Authentication

​Request Body

​Request Example

​Response

​Response Example

​Error Responses

​Use Cases

​Handling Signup Webhooks

​Idempotent Referral Creation

​Batch Referral Creation

​Best Practices

​Workflow

​Rate Limits

Authorizations

Body

Response

Overview

Authentication

Request Body

Request Example

Response

Response Example

Error Responses

Use Cases

Handling Signup Webhooks

Idempotent Referral Creation

Batch Referral Creation

Best Practices

Workflow

Rate Limits