List Posters

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

programId

string

Filter results to only include posters from a specific program. Useful when analyzing poster performance for individual programs.Example: programId=prog_123abc

studentId

string

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

limit

integer

default:"50"

Maximum number of results to return per page. Default is 50, maximum is typically 100.Example: limit=25

offset

integer

default:"0"

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 "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:

posters

array

required

Array of poster objects, each containing information about a poster placement.

Each poster object contains:

string

required

Unique identifier for the poster.

program_id

string

required

ID of the program this poster belongs to.

student_id

string

required

ID of the student ambassador who placed this poster.

qr_code_url

string

required

URL to the QR code image for this poster.

location

string

Physical location where the poster was placed (if provided).

created_at

string

required

ISO 8601 timestamp of when the poster was created.

metadata

object

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(
    `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 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

401

object

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

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

studentId

string

Filter by student (ambassador) ID

limit

integer

default:50

Maximum number of results to return

offset

integer

default:0

Number of results to skip

Response

List of posters

The response is of type object.

API Documentation

Users

Referrals

Posters

Impressions

Earnings

Overview

Authentication

Query Parameters

Request Example

Response

Response Example

Use Cases

Building a Poster Dashboard

Tracking Ambassador Activity

Exporting Poster Data

Best Practices

Error Responses

Rate Limits

Authorizations

Query Parameters

Response

API Documentation

Users

Referrals

Posters

Impressions

Earnings

​Overview

​Authentication

​Query Parameters

​Request Example

​Response

​Response Example

​Use Cases

​Building a Poster Dashboard

​Tracking Ambassador Activity

​Exporting Poster Data

​Best Practices

​Error Responses

​Rate Limits

Authorizations

Query Parameters

Response

Overview

Authentication

Query Parameters

Request Example

Response

Response Example

Use Cases

Building a Poster Dashboard

Tracking Ambassador Activity

Exporting Poster Data

Best Practices

Error Responses

Rate Limits