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"
}
]
}
Users
List Users
Retrieve a list of all students who are ambassadors in your programs
GET
/
api
/
v1
/
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.
Page 2 (next 50 users):
Page 3 (next 50 users):
Continue incrementing the
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
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_123abcMaximum 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 pageNumber 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 resultsRequest 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: Each user object in the array contains: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 thelimit and offset parameters:
Page 1 (first 50 users):
GET /api/v1/users?limit=50&offset=0
GET /api/v1/users?limit=50&offset=50
GET /api/v1/users?limit=50&offset=100
offset by the limit value for each subsequent page.
Error Responses
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
limitandoffsetfor large datasets to avoid timeouts - Filter by program - Use
programIdto 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 allowedX-RateLimit-Remaining- Remaining requests in current windowX-RateLimit-Reset- Time when the rate limit resets
Authorizations
Query Parameters
Was this page helpful?