# Get all posters
curl -X GET "https://vantio.app/api/v1/posters" \
-H "Authorization: Bearer sk_your_secret_key_here"
# Get posters from a specific program
curl -X GET "https://vantio.app/api/v1/posters?programId=prog_123abc&limit=100" \
-H "Authorization: Bearer sk_your_secret_key_here"
# Get posters from a specific ambassador
curl -X GET "https://vantio.app/api/v1/posters?studentId=user_123abc" \
-H "Authorization: Bearer sk_your_secret_key_here"
{
"posters": [
{
"id": "poster_123abc",
"program_id": "prog_123abc",
"student_id": "user_123abc",
"qr_code_url": "https://example.com/qr-codes/poster_123abc.png",
"location": "Campus Center - Main Entrance",
"created_at": "2024-01-15T10:30:00Z",
"metadata": {
"poster_type": "standard",
"placement_date": "2024-01-15"
}
},
{
"id": "poster_456def",
"program_id": "prog_123abc",
"student_id": "user_456def",
"qr_code_url": "https://example.com/qr-codes/poster_456def.png",
"location": "Library - First Floor",
"created_at": "2024-01-16T14:20:00Z",
"metadata": {
"poster_type": "premium",
"placement_date": "2024-01-16"
}
}
]
}
Posters
List Posters
Retrieve a list of all posters placed by ambassadors in your programs
GET
/
api
/
v1
/
posters
# Get all posters
curl -X GET "https://vantio.app/api/v1/posters" \
-H "Authorization: Bearer sk_your_secret_key_here"
# Get posters from a specific program
curl -X GET "https://vantio.app/api/v1/posters?programId=prog_123abc&limit=100" \
-H "Authorization: Bearer sk_your_secret_key_here"
# Get posters from a specific ambassador
curl -X GET "https://vantio.app/api/v1/posters?studentId=user_123abc" \
-H "Authorization: Bearer sk_your_secret_key_here"
{
"posters": [
{
"id": "poster_123abc",
"program_id": "prog_123abc",
"student_id": "user_123abc",
"qr_code_url": "https://example.com/qr-codes/poster_123abc.png",
"location": "Campus Center - Main Entrance",
"created_at": "2024-01-15T10:30:00Z",
"metadata": {
"poster_type": "standard",
"placement_date": "2024-01-15"
}
},
{
"id": "poster_456def",
"program_id": "prog_123abc",
"student_id": "user_456def",
"qr_code_url": "https://example.com/qr-codes/poster_456def.png",
"location": "Library - First Floor",
"created_at": "2024-01-16T14:20:00Z",
"metadata": {
"poster_type": "premium",
"placement_date": "2024-01-16"
}
}
]
}
Retrieve a list of all posters placed by ambassadors in your programs. This endpoint helps you track poster placements, monitor ambassador activity, and analyze poster performance.
Overview
The List Posters endpoint returns a paginated list of all poster placements created by student ambassadors. Use this endpoint to:- Track all poster placements across programs
- Monitor which ambassadors are most active
- Filter posters by program or student
- Build analytics dashboards for poster performance
- Export poster data for reporting
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 posters from a specific program. Useful when analyzing poster performance for individual programs.Example:
programId=prog_123abcFilter results to only include posters placed by a specific student ambassador. Use this to see all posters placed by a particular ambassador.Example:
studentId=user_123abcMaximum number of results to return per page. Default is 50, maximum is typically 100.Example:
limit=25Number of results to skip before starting to return results. Use for pagination.Example:
offset=50 skips the first 50 resultsRequest Example
# Get all posters
curl -X GET "https://vantio.app/api/v1/posters" \
-H "Authorization: Bearer sk_your_secret_key_here"
# Get posters from a specific program
curl -X GET "https://vantio.app/api/v1/posters?programId=prog_123abc&limit=100" \
-H "Authorization: Bearer sk_your_secret_key_here"
# Get posters from a specific ambassador
curl -X GET "https://vantio.app/api/v1/posters?studentId=user_123abc" \
-H "Authorization: Bearer sk_your_secret_key_here"
Response
The API returns a JSON object containing an array of poster objects: Each poster object contains:Response Example
{
"posters": [
{
"id": "poster_123abc",
"program_id": "prog_123abc",
"student_id": "user_123abc",
"qr_code_url": "https://example.com/qr-codes/poster_123abc.png",
"location": "Campus Center - Main Entrance",
"created_at": "2024-01-15T10:30:00Z",
"metadata": {
"poster_type": "standard",
"placement_date": "2024-01-15"
}
},
{
"id": "poster_456def",
"program_id": "prog_123abc",
"student_id": "user_456def",
"qr_code_url": "https://example.com/qr-codes/poster_456def.png",
"location": "Library - First Floor",
"created_at": "2024-01-16T14:20:00Z",
"metadata": {
"poster_type": "premium",
"placement_date": "2024-01-16"
}
}
]
}
Use Cases
Building a Poster Dashboard
Fetch all posters and display them in a dashboard:async function fetchPosters(filters = {}) {
const params = new URLSearchParams();
if (filters.programId) params.append('programId', filters.programId);
if (filters.studentId) params.append('studentId', filters.studentId);
if (filters.limit) params.append('limit', filters.limit);
if (filters.offset) params.append('offset', filters.offset);
const response = await fetch(
`https://vantio.app/api/v1/posters?${params.toString()}`,
{
headers: {
'Authorization': `Bearer ${API_KEY}`
}
}
);
return await response.json();
}
Tracking Ambassador Activity
See which ambassadors are most active in placing posters:async function getAmbassadorPosterStats(programId) {
const posters = await fetchPosters({ programId, limit: 1000 });
// Count posters by student
const stats = {};
posters.posters.forEach(poster => {
if (!stats[poster.student_id]) {
stats[poster.student_id] = 0;
}
stats[poster.student_id]++;
});
return stats;
}
Exporting Poster Data
Fetch all posters for export:async function exportAllPosters(programId) {
let allPosters = [];
let offset = 0;
const limit = 100;
let hasMore = true;
while (hasMore) {
const response = await fetch(
`https://vantio.app/api/v1/posters?programId=${programId}&limit=${limit}&offset=${offset}`,
{
headers: {
'Authorization': `Bearer ${API_KEY}`
}
}
);
const data = await response.json();
allPosters = [...allPosters, ...data.posters];
hasMore = data.posters.length === limit;
offset += limit;
}
return allPosters;
}
Best Practices
- Use filters effectively - Combine programId and studentId to narrow results
- Implement pagination - Always use
limitandoffsetfor large datasets - Cache poster data - Poster lists don’t change frequently
- Track locations - Use metadata to store location details for analytics
- Monitor QR code usage - Link posters to impressions to track scan rates
Error Responses
Unauthorized - Invalid or missing API key
{
"error": "Unauthorized",
"message": "Invalid or missing API key"
}
Rate Limits
This endpoint is subject to rate limiting. Check response headers for rate limit information.Authorizations
Query Parameters
Response
List of posters
The response is of type object.
Was this page helpful?