API Structure & Navigation

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)

Start with a Program - Programs contain all other resources
Find Users - Users are ambassadors in programs
Track Posters - Posters are placed by users
Monitor Impressions - Impressions come from poster scans
Create Referrals - Referrals link to impressions
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');

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
  };
}

In addition to the API, you can navigate resources in the Vantio Dashboard:

Programs - View and manage all programs
Users - Browse student ambassadors
Referrals - Track signups and conversions
Posters - Manage QR code posters
Impressions - View scan analytics
Earnings - Monitor commissions and payouts

Best Practices

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

Next Steps

Explore the API Reference for detailed endpoint documentation
Check Code Examples for navigation patterns
Review Integration Patterns for reusable code

Get Started

Essentials

API Structure & Navigation

API Structure Overview

Resource Groups

Users

Referrals

Posters

Impressions

Earnings

Resource Relationships

Navigation Flow

Filtering Resources

By Program

By User/Student

By Status

Common Navigation Patterns

Get All Data for a Program

Follow the Referral Chain

Dashboard Navigation

Best Practices

Next Steps

​API Structure Overview

​Resource Groups

​Users

​Referrals

​Posters

​Impressions

​Earnings

​Resource Relationships

​Navigation Flow

​Filtering Resources

​By Program

​By User/Student

​By Status

​Pagination

​Common Navigation Patterns

​Get All Data for a Program

​Follow the Referral Chain

​Dashboard Navigation

​Best Practices

​Next Steps

API Structure Overview

Resource Groups

Users

Referrals

Posters

Impressions

Earnings

Resource Relationships

Navigation Flow

Filtering Resources

By Program

By User/Student

By Status

Pagination

Common Navigation Patterns

Get All Data for a Program

Follow the Referral Chain

Dashboard Navigation

Best Practices

Next Steps