Skip to main content

​
Overview

This guide will walk you through integrating Vantio into your platform. You’ll learn how to:
  • Set up API authentication
  • Create your first program
  • Generate QR codes for ambassadors
  • Track referrals and earnings

​
Step 1: Get Your API Key

Before you can use the Vantio API, you need to obtain your secret API key.
  1. Log in to your Vantio Dashboard
  2. Navigate to Settings → API Keys
  3. Click Create New API Key
  4. Copy your secret key (it starts with sk_)
Keep your API key secure! Never expose it in client-side code or commit it to version control. Store it as an environment variable.

​
Step 2: Set Up Authentication

All Vantio API requests require authentication using a Bearer token. Include your API key in the Authorization header: 
Authorization: Bearer sk_your_secret_key_here

​
Example: Making Your First Request

Test your API key by fetching your users: 
curl -X GET "https://vantio.app/api/v1/users" \
  -H "Authorization: Bearer sk_your_secret_key_here"

​
Step 3: Create a Program

Programs are the foundation of your referral system. Each program can have multiple ambassadors and track referrals independently.
The easiest way to create a program is through the Vantio Dashboard:
  1. Go to Programs in your dashboard
  2. Click Create New Program
  3. Fill in program details (name, description, commission rates)
  4. Save your program
You can also create programs programmatically using the API (if program creation endpoints are available in your plan).

​
Step 4: Add Student Ambassadors

Student ambassadors are the users who will place posters and generate referrals.

​
Add Ambassadors via Dashboard

  1. Navigate to Users in your dashboard
  2. Click Add User or Invite Ambassador
  3. Enter student information (name, email, program assignment)
  4. The student will receive an invitation email

​
Add Ambassadors via API

// Example: Adding a user (if user creation endpoint exists)
const response = await fetch('https://vantio.app/api/v1/users', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    first_name: 'John',
    last_name: 'Doe',
    email: '[email protected]',
    program_id: 'prog_123abc'
  })
});

​
Step 5: Generate QR Code Posters

Each ambassador needs QR code posters to place around campus. Posters link scans to the ambassador who placed them.

​
View Posters via API

// Fetch all posters for a program
const response = await fetch(
  'https://vantio.app/api/v1/posters?programId=prog_123abc',
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

const data = await response.json();
console.log('Posters:', data.posters);
Each poster has a qr_code_url that you can download or display to ambassadors.

​
Step 6: Track the Referral Flow

The Vantio referral flow works like this:
  1. QR Code Scan → Creates an impression
  2. User Signs Up → Create a referral linked to the impression
  3. User Makes Purchase → Create an earning linked to the referral

​
Example: Creating a Referral

When a user signs up after scanning a QR code: 
async function createReferral(impressionId, signupData) {
  const response = await fetch('https://vantio.app/api/v1/referrals', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      impression_id: impressionId, // From the QR scan
      first_name: signupData.firstName,
      last_name: signupData.lastName,
      email: signupData.email
    })
  });
  
  return await response.json();
}

​
Example: Creating an Earning

When a referred customer makes a purchase: 
async function createEarning(referralId, orderTotal) {
  const commissionRate = 0.10; // 10% commission
  const amountInCents = Math.round(orderTotal * commissionRate * 100);
  
  const response = await fetch('https://vantio.app/api/v1/earnings', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      referral_id: referralId,
      amount: amountInCents, // Amount in cents
      currency: 'USD',
      type: 'purchase',
      description: `Commission from purchase`,
      idempotency_key: `earn_${Date.now()}` // Prevent duplicates
    })
  });
  
  return await response.json();
}

​
Step 7: Monitor Performance

Track your referral program’s performance using the API: 
// Get all referrals
const referrals = await fetch(
  'https://vantio.app/api/v1/referrals?programId=prog_123abc',
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

// Get all earnings
const earnings = await fetch(
  'https://vantio.app/api/v1/earnings?programId=prog_123abc&status=paid',
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

​
Next Steps

API Authentication Guide

Learn more about authentication and making API requests

Code Examples

Explore more code examples and integration patterns

API Reference

Browse the complete API documentation

​
Need Help?

If you run into any issues:
  • Check the API Reference for detailed endpoint documentation
  • Review Code Examples for common integration patterns
  • Contact support through your dashboard