Skip to main content
GET
/
api
/
v1
/
referrals
# Get all referrals
curl -X GET "http://localhost:3000/api/v1/referrals" \
  -H "Authorization: Bearer sk_your_secret_key_here"

# Get converted referrals from a specific program
curl -X GET "http://localhost:3000/api/v1/referrals?programId=prog_123abc&status=converted&limit=100" \
  -H "Authorization: Bearer sk_your_secret_key_here"

# Get referrals from a specific ambassador
curl -X GET "http://localhost:3000/api/v1/referrals?studentId=user_123abc" \
  -H "Authorization: Bearer sk_your_secret_key_here"

{
  "referrals": [
    {
      "id": "ref_123abc",
      "impression_id": "imp_456def",
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice.johnson@example.com",
      "status": "converted",
      "program_id": "prog_123abc",
      "student_id": "user_123abc",
      "created_at": "2024-01-15T10:30:00Z",
      "verified_at": "2024-01-16T14:20:00Z",
      "metadata": {
        "source": "poster_qr_code",
        "location": "campus_center"
      }
    },
    {
      "id": "ref_789ghi",
      "impression_id": "imp_012jkl",
      "first_name": "Bob",
      "last_name": "Williams",
      "email": "bob.williams@example.com",
      "status": "pending",
      "program_id": "prog_123abc",
      "student_id": "user_456def",
      "created_at": "2024-01-17T09:15:00Z",
      "verified_at": null
    }
  ]
}
Retrieve a list of all referrals (signups) from your programs. This endpoint supports filtering by program, student, and status, making it easy to track conversions and manage your referral pipeline.

​
Overview

The List Referrals endpoint returns a paginated list of all referrals created through your ambassador programs. Use this endpoint to:
  • Track all signups from referral links
  • Filter referrals by program or ambassador
  • Monitor referral status (pending, converted, verified, rejected)
  • Build analytics dashboards
  • Export referral data for reporting

​
Authentication

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

​
Query Parameters

​
programId
string
Filter results to only include referrals from a specific program. Useful when analyzing performance of individual programs.Example: programId=prog_123abc
​
studentId
string
Filter results to only include referrals from a specific student ambassador. Use this to see all referrals generated by a particular ambassador.Example: studentId=user_123abc
​
status
string
Filter referrals by their current status. Valid values are:
  • pending - Referral created but not yet converted
  • converted - Referral has converted (made a purchase/subscription)
  • verified - Referral has been verified
  • rejected - Referral was rejected
Example: status=converted returns only converted referrals
​
limit
integer
default:"50"
Maximum number of results to return per page. Default is 50, maximum is typically 100.Example: limit=25
​
offset
integer
default:"0"
Number of results to skip before starting to return results. Use for pagination.Example: offset=50 skips the first 50 results

​
Request Example

# Get all referrals
curl -X GET "http://localhost:3000/api/v1/referrals" \
  -H "Authorization: Bearer sk_your_secret_key_here"

# Get converted referrals from a specific program
curl -X GET "http://localhost:3000/api/v1/referrals?programId=prog_123abc&status=converted&limit=100" \
  -H "Authorization: Bearer sk_your_secret_key_here"

# Get referrals from a specific ambassador
curl -X GET "http://localhost:3000/api/v1/referrals?studentId=user_123abc" \
  -H "Authorization: Bearer sk_your_secret_key_here"

​
Response

The API returns a JSON object containing an array of referral objects:
​
referrals
array
required
Array of referral objects, each containing information about a referral signup.
Each referral object contains:
​
id
string
required
Unique identifier for the referral.
​
impression_id
string
required
ID of the impression (QR scan) that led to this referral.
​
first_name
string
required
First name of the referred person.
​
last_name
string
required
Last name of the referred person.
​
email
string
required
Email address of the referred person.
​
status
string
required
Current status of the referral: pending, converted, verified, or rejected.
​
program_id
string
required
ID of the program this referral belongs to.
​
student_id
string
required
ID of the student ambassador who generated this referral.
​
created_at
string
required
ISO 8601 timestamp of when the referral was created.
​
verified_at
string
ISO 8601 timestamp of when the referral was verified, if applicable.

​
Response Example

{
  "referrals": [
    {
      "id": "ref_123abc",
      "impression_id": "imp_456def",
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice.johnson@example.com",
      "status": "converted",
      "program_id": "prog_123abc",
      "student_id": "user_123abc",
      "created_at": "2024-01-15T10:30:00Z",
      "verified_at": "2024-01-16T14:20:00Z",
      "metadata": {
        "source": "poster_qr_code",
        "location": "campus_center"
      }
    },
    {
      "id": "ref_789ghi",
      "impression_id": "imp_012jkl",
      "first_name": "Bob",
      "last_name": "Williams",
      "email": "bob.williams@example.com",
      "status": "pending",
      "program_id": "prog_123abc",
      "student_id": "user_456def",
      "created_at": "2024-01-17T09:15:00Z",
      "verified_at": null
    }
  ]
}

​
Use Cases

​
Building a Referral Dashboard

Fetch all referrals and display them in a dashboard with filtering: 
async function fetchReferrals(filters = {}) {
  const params = new URLSearchParams();
  
  if (filters.programId) params.append('programId', filters.programId);
  if (filters.studentId) params.append('studentId', filters.studentId);
  if (filters.status) params.append('status', filters.status);
  if (filters.limit) params.append('limit', filters.limit);
  if (filters.offset) params.append('offset', filters.offset);
  
  const response = await fetch(
    `http://localhost:3000/api/v1/referrals?${params.toString()}`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );
  
  return await response.json();
}

​
Tracking Conversion Rates

Calculate conversion rates by status: 
async function getConversionStats(programId) {
  const allReferrals = await fetchReferrals({ programId, limit: 1000 });
  const converted = await fetchReferrals({ programId, status: 'converted', limit: 1000 });
  
  const total = allReferrals.referrals.length;
  const convertedCount = converted.referrals.length;
  const conversionRate = (convertedCount / total) * 100;
  
  return {
    total,
    converted: convertedCount,
    conversionRate: conversionRate.toFixed(2) + '%'
  };
}

​
Exporting Referral Data

Fetch all referrals for export: 
async function exportAllReferrals(programId) {
  let allReferrals = [];
  let offset = 0;
  const limit = 100;
  let hasMore = true;
  
  while (hasMore) {
    const response = await fetch(
      `http://localhost:3000/api/v1/referrals?programId=${programId}&limit=${limit}&offset=${offset}`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    );
    
    const data = await response.json();
    allReferrals = [...allReferrals, ...data.referrals];
    
    hasMore = data.referrals.length === limit;
    offset += limit;
  }
  
  return allReferrals;
}

​
Best Practices

  1. Use filters wisely - Combine filters to narrow down results and reduce response size
  2. Implement pagination - Always use limit and offset for large datasets
  3. Cache frequently accessed data - Referral lists don’t change as frequently as other data
  4. Monitor status changes - Set up webhooks or polling to track status updates
  5. Handle empty results - Always check if the referrals array is empty

​
Error Responses

​
401
object
Unauthorized - Invalid or missing API key
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

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

Query Parameters

​
programId
string

Filter by program ID

​
studentId
string

Filter by student (ambassador) ID

​
status
enum<string>

Filter by referral status

Available options:
pending,
converted,
verified,
rejected
​
limit
integer
default:50

Maximum number of results to return

​
offset
integer
default:0

Number of results to skip

Response

List of referrals

The response is of type object.