List Users

curl -X GET "https://vantio.app/api/v1/users?programId=prog_123abc&limit=25&offset=0" \
  -H "Authorization: Bearer sk_your_secret_key_here"

{
  "users": [
    {
      "id": "user_123abc",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "program_id": "prog_123abc",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "user_456def",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com",
      "program_id": "prog_123abc",
      "created_at": "2024-01-16T14:20:00Z"
    }
  ]
}

GET

api

users

curl -X GET "https://vantio.app/api/v1/users?programId=prog_123abc&limit=25&offset=0" \
  -H "Authorization: Bearer sk_your_secret_key_here"

{
  "users": [
    {
      "id": "user_123abc",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "program_id": "prog_123abc",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "user_456def",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com",
      "program_id": "prog_123abc",
      "created_at": "2024-01-16T14:20:00Z"
    }
  ]
}

Retrieve a list of all students who are ambassadors in your programs. This endpoint supports filtering and pagination to help you manage large directories of student ambassadors.

Overview

The List Users endpoint returns a paginated list of all student ambassadors enrolled in your referral programs. Use this endpoint to:

View all ambassadors across your programs
Filter ambassadors by program
Implement pagination for large datasets
Build dashboards showing ambassador statistics

Authentication

This endpoint requires authentication using a Bearer token in the Authorization header:

Authorization: Bearer sk_your_secret_key_here

Query Parameters

string

Filter results to only include users from a specific program. This is useful when you want to see ambassadors for a particular program.Example: programId=prog_123abc

integer

default:"50"

Maximum number of results to return per page. The default is 50, and the maximum is typically 100. Use this parameter along with offset to implement pagination.Example: limit=25 returns 25 users per page

integer

default:"0"

Number of results to skip before starting to return results. Use this for pagination - if you’re on page 2 with a limit of 50, set offset to 50.Example: offset=50 skips the first 50 results

Request Example

curl -X GET "https://vantio.app/api/v1/users?programId=prog_123abc&limit=25&offset=0" \
  -H "Authorization: Bearer sk_your_secret_key_here"

Response

The API returns a JSON object containing an array of user objects:

array

required

Array of user objects, each containing information about a student ambassador.

Each user object in the array contains:

string

required

Unique identifier for the user (student ambassador).

string

required

First name of the student ambassador.

string

required

Last name of the student ambassador.

string

required

Email address of the student ambassador.

string

required

ID of the program this user belongs to.

string

required

ISO 8601 timestamp of when the user was created.

Response Example

{
  "users": [
    {
      "id": "user_123abc",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "program_id": "prog_123abc",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "user_456def",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com",
      "program_id": "prog_123abc",
      "created_at": "2024-01-16T14:20:00Z"
    }
  ]
}

Pagination

To paginate through results, use the limit and offset parameters: Page 1 (first 50 users):

GET /api/v1/users?limit=50&offset=0

Page 2 (next 50 users):

GET /api/v1/users?limit=50&offset=50

Page 3 (next 50 users):

GET /api/v1/users?limit=50&offset=100

Continue incrementing the offset by the limit value for each subsequent page.

Error Responses

object

Unauthorized - Invalid or missing API key

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

Use Cases

Building an Ambassador Dashboard

Use this endpoint to fetch all ambassadors and display them in a dashboard:

async function fetchAllAmbassadors(programId) {
  const response = await fetch(
    `https://vantio.app/api/v1/users?programId=${programId}&limit=100`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );
  
  const data = await response.json();
  return data.users;
}

Implementing Pagination

For large datasets, implement pagination to improve performance:

async function fetchUsersPage(page = 1, pageSize = 50) {
  const offset = (page - 1) * pageSize;
  const response = await fetch(
    `https://vantio.app/api/v1/users?limit=${pageSize}&offset=${offset}`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );
  
  return await response.json();
}

Best Practices

Use pagination - Always use limit and offset for large datasets to avoid timeouts
Filter by program - Use programId to narrow results when you only need users from specific programs
Cache results - User lists don’t change frequently, so consider caching responses
Handle errors - Always check for 401 errors and prompt users to refresh their API key

Rate Limits

This endpoint is subject to rate limiting. Check the 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

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

limit

integer

default:50

Maximum number of results to return

offset

integer

default:0

Number of results to skip

Response

List of users

users

object[]

API Documentation

Users

Referrals

Posters

Impressions

Earnings

Overview

Authentication

Query Parameters

Request Example

Response

Response Example

Error Responses

Use Cases

Building an Ambassador Dashboard

Best Practices

Rate Limits

Authorizations

Query Parameters

Response

​Overview

​Authentication

​Query Parameters

​Request Example

​Response

​Response Example

​Pagination

​Error Responses

​Use Cases

​Building an Ambassador Dashboard

​Implementing Pagination

​Best Practices

​Rate Limits

Authorizations

Query Parameters

Response

Overview

Authentication

Query Parameters

Request Example

Response

Response Example

Pagination

Error Responses

Use Cases

Building an Ambassador Dashboard

Implementing Pagination

Best Practices

Rate Limits