Skip to main content

​
API Structure Overview

The Vantio API is organized into resource groups that represent different aspects of your referral program. Understanding this structure helps you navigate the API effectively.

​
Resource Groups

The Vantio API is organized into five main resource groups:

​
Users

Student ambassadors enrolled in your programs. Endpoints:
  • GET /api/v1/users - List all users
  • GET /api/v1/users/{id} - Get specific user
Use Cases:
  • View all ambassadors
  • Get ambassador details
  • Filter by program

​
Referrals

Signups and conversions from your referral program. Endpoints:
  • GET /api/v1/referrals - List referrals
  • POST /api/v1/referrals - Create referral
  • GET /api/v1/referrals/{id} - Get referral
  • PUT /api/v1/referrals/{id} - Update referral
Use Cases:
  • Track signups
  • Monitor conversions
  • Update referral status

​
Posters

QR code posters placed by ambassadors. Endpoints:
  • GET /api/v1/posters - List posters
  • GET /api/v1/posters/{id} - Get poster
Use Cases:
  • View all poster placements
  • Download QR codes
  • Track poster performance

​
Impressions

QR code scans and engagement tracking. Endpoints:
  • GET /api/v1/impressions - List impressions
  • GET /api/v1/impressions/{id} - Get impression
Use Cases:
  • Track QR code scans
  • Monitor engagement
  • Analyze scan patterns

​
Earnings

Commissions and payouts for ambassadors. Endpoints:
  • GET /api/v1/earnings - List earnings
  • POST /api/v1/earnings - Create earning
  • GET /api/v1/earnings/{id} - Get earning
  • PUT /api/v1/earnings/{id} - Update earning
Use Cases:
  • Track commissions
  • Process payouts
  • Monitor earnings status

​
Resource Relationships

Understanding how resources relate helps you navigate the API: 
Program
  ├── Users (Ambassadors)
  │     ├── Posters
  │     │     └── Impressions (QR Scans)
  │     │           └── Referrals (Signups)
  │     │                 └── Earnings (Commissions)
  1. Start with a Program - Programs contain all other resources
  2. Find Users - Users are ambassadors in programs
  3. Track Posters - Posters are placed by users
  4. Monitor Impressions - Impressions come from poster scans
  5. Create Referrals - Referrals link to impressions
  6. Generate Earnings - Earnings link to referrals

​
Filtering Resources

Most list endpoints support filtering to help you navigate:

​
By Program

// Get all resources for a specific program
const users = await fetch('/api/v1/users?programId=prog_123abc');
const referrals = await fetch('/api/v1/referrals?programId=prog_123abc');
const posters = await fetch('/api/v1/posters?programId=prog_123abc');

​
By User/Student

// Get resources for a specific ambassador
const referrals = await fetch('/api/v1/referrals?studentId=user_123abc');
const posters = await fetch('/api/v1/posters?studentId=user_123abc');

​
By Status

// Filter by status
const referrals = await fetch('/api/v1/referrals?status=converted');
const earnings = await fetch('/api/v1/earnings?status=paid');

​
Pagination

Navigate through large result sets using pagination: 
// Page 1
const page1 = await fetch('/api/v1/referrals?limit=50&offset=0');

// Page 2
const page2 = await fetch('/api/v1/referrals?limit=50&offset=50');

// Page 3
const page3 = await fetch('/api/v1/referrals?limit=50&offset=100');

​
Common Navigation Patterns

​
Get All Data for a Program

async function getProgramData(programId) {
  const [users, referrals, posters, impressions, earnings] = await Promise.all([
    fetch(`/api/v1/users?programId=${programId}`),
    fetch(`/api/v1/referrals?programId=${programId}`),
    fetch(`/api/v1/posters?programId=${programId}`),
    fetch(`/api/v1/impressions?programId=${programId}`),
    fetch(`/api/v1/earnings?program_id=${programId}`)
  ]);
  
  return {
    users: await users.json(),
    referrals: await referrals.json(),
    posters: await posters.json(),
    impressions: await impressions.json(),
    earnings: await earnings.json()
  };
}

​
Follow the Referral Chain

async function getReferralChain(impressionId) {
  // Get the impression
  const impression = await fetch(`/api/v1/impressions/${impressionId}`);
  
  // Get referrals from this impression
  const referrals = await fetch(
    `/api/v1/referrals?impression_id=${impressionId}`
  );
  
  // Get earnings for each referral
  const earningsPromises = referrals.map(ref =>
    fetch(`/api/v1/earnings?referral_id=${ref.id}`)
  );
  const earnings = await Promise.all(earningsPromises);
  
  return {
    impression,
    referrals,
    earnings
  };
}

​
Dashboard Navigation

In addition to the API, you can navigate resources in the Vantio Dashboard:
  1. Programs - View and manage all programs
  2. Users - Browse student ambassadors
  3. Referrals - Track signups and conversions
  4. Posters - Manage QR code posters
  5. Impressions - View scan analytics
  6. Earnings - Monitor commissions and payouts

​
Best Practices

  1. Start with programs - Programs are the top-level organization
  2. Use filters - Narrow results to what you need
  3. Follow relationships - Use IDs to navigate between resources
  4. Implement pagination - Handle large datasets efficiently
  5. Cache frequently accessed data - Reduce API calls

​
Next Steps