Skip to main content

​
Authentication Overview

All Vantio API endpoints require authentication using a Bearer token. Your API key should be included in the Authorization header of every request.

​
Getting Your API Key

  1. Log in to your Vantio Dashboard
  2. Navigate to Settings → API Keys
  3. Create a new API key or copy an existing one
  4. Your API key starts with sk_
Never expose your API key in client-side code, commit it to version control, or share it publicly. Treat it like a password.

​
Authentication Header

Include your API key in the Authorization header: 
Authorization: Bearer sk_your_secret_key_here

​
Making API Requests

​
Using cURL

curl -X GET "https://vantio.app/api/v1/users" \
  -H "Authorization: Bearer sk_your_secret_key_here"

​
Using JavaScript (Fetch API)

const API_KEY = process.env.VANTIO_API_KEY;

const response = await fetch('https://vantio.app/api/v1/users', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`
  }
});

const data = await response.json();

​
Using JavaScript (Axios)

const axios = require('axios');

const response = await axios.get('https://vantio.app/api/v1/users', {
  headers: {
    'Authorization': `Bearer ${process.env.VANTIO_API_KEY}`
  }
});

const data = response.data;

​
Using Python (Requests)

import os
import requests

api_key = os.environ.get('VANTIO_API_KEY')
headers = {
    'Authorization': f'Bearer {api_key}'
}

response = requests.get(
    'https://vantio.app/api/v1/users',
    headers=headers
)

data = response.json()

​
Request Methods

The Vantio API uses standard HTTP methods:
MethodUsageExample
GETRetrieve resourcesList users, get referral details
POSTCreate resourcesCreate referral, create earning
PUTUpdate resourcesUpdate referral status, update earning

​
Request Body Format

For POST and PUT requests, send JSON data in the request body: 
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: 'imp_123abc',
    first_name: 'John',
    last_name: 'Doe',
    email: '[email protected]'
  })
});

​
Query Parameters

Many endpoints support query parameters for filtering and pagination: 
// Filter referrals by program and status
const response = await fetch(
  'https://vantio.app/api/v1/referrals?programId=prog_123abc&status=converted&limit=50',
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

​
Response Format

All successful API responses return JSON: 
{
  "id": "ref_123abc",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "status": "pending"
}

​
Error Responses

The API uses standard HTTP status codes:
  • 200 - Success
  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (invalid or missing API key)
  • 404 - Not Found (resource doesn’t exist)
Error responses include a message: 
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

​
Handling Errors

Always check the response status and handle errors appropriately: 
async function fetchUsers() {
  try {
    const response = await fetch('https://vantio.app/api/v1/users', {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    });
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message || 'API request failed');
    }
    
    return await response.json();
  } catch (error) {
    console.error('Error fetching users:', error);
    throw error;
  }
}

​
Rate Limits

The Vantio API enforces rate limits to ensure fair usage. Check response headers for rate limit information:
  • X-RateLimit-Limit - Maximum requests allowed
  • X-RateLimit-Remaining - Remaining requests in current window
  • X-RateLimit-Reset - Time when the rate limit resets

​
Best Practices

  1. Store API keys securely - Use environment variables, never hardcode
  2. Handle errors gracefully - Always check response status codes
  3. Use idempotency keys - For POST requests that might be retried
  4. Implement retry logic - For transient failures (with exponential backoff)
  5. Cache responses - When appropriate to reduce API calls

​
Environment Variables

Store your API key as an environment variable: 
# .env file
VANTIO_API_KEY=sk_your_secret_key_here

// Access in your code
const API_KEY = process.env.VANTIO_API_KEY;