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_123abc
Filter 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_123abc
Maximum number of results to return per page. Default is 50, maximum is typically 100.Example: limit=25
Number of results to skip before starting to return results. Use for pagination.Example: offset=50 skips the first 50 results
Request Example
# Get all posters
curl -X GET "http://localhost:3000/api/v1/posters" \
-H "Authorization: Bearer sk_your_secret_key_here"
# Get posters from a specific program
curl -X GET "http://localhost:3000/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 "http://localhost:3000/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:
Array of poster objects, each containing information about a poster placement.
Unique identifier for the poster.
ID of the program this poster belongs to.
ID of the student ambassador who placed this poster.
URL to the QR code image for this poster.
Physical location where the poster was placed (if provided).
ISO 8601 timestamp of when the poster was created.
Additional metadata about the poster placement.
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(
`http://localhost:3000/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(
`http://localhost:3000/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
limit and offset for 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.Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Filter by student (ambassador) ID
Maximum number of results to return
Number of results to skip
The response is of type object.
