List Referrals

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 "https://vantio.app/api/v1/referrals" \
  -H "Authorization: Bearer sk_your_secret_key_here"

# Get converted referrals from a specific program
curl -X GET "https://vantio.app/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 "https://vantio.app/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:

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.

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(
    `https://vantio.app/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(
      `https://vantio.app/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

Use filters wisely - Combine filters to narrow down results and reduce response size
Implement pagination - Always use limit and offset for large datasets
Cache frequently accessed data - Referral lists don’t change as frequently as other data
Monitor status changes - Set up webhooks or polling to track status updates
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.

API Documentation

Users

Referrals

Posters

Impressions

Earnings

List Referrals

Overview

Authentication

Query Parameters

Request Example

Response

Response Example

Use Cases

Building a Referral Dashboard

Tracking Conversion Rates

Exporting Referral Data

Best Practices

Error Responses

Rate Limits

Authorizations

Query Parameters

Response

API Documentation

Users

Referrals

Posters

Impressions

Earnings

Documentation Index

​Overview

​Authentication

​Query Parameters

​Request Example

​Response

​Response Example

​Use Cases

​Building a Referral Dashboard

​Tracking Conversion Rates

​Exporting Referral Data

​Best Practices

​Error Responses

​Rate Limits

Authorizations

Query Parameters

Response

Overview

Authentication

Query Parameters

Request Example

Response

Response Example

Use Cases

Building a Referral Dashboard

Tracking Conversion Rates

Exporting Referral Data

Best Practices

Error Responses

Rate Limits