Retrieve detailed information about a specific poster placement by its unique ID. Use this endpoint to fetch complete poster details including QR code URL, location, and associated metadata.
Overview
The Get Poster endpoint returns comprehensive information about a single poster placement. This is useful for:
- Displaying poster details in dashboards
- Viewing QR code information
- Checking poster placement details
- Building poster detail pages
- Linking posters to impressions and referrals
Authentication
This endpoint requires authentication using a Bearer token in the Authorization header:
Authorization: Bearer sk_your_secret_key_here
Path Parameters
The unique identifier of the poster you want to retrieve. This ID is returned when you list posters or create a new poster.Example: poster_123abc
Request Example
curl -X GET "http://localhost:3000/api/v1/posters/poster_123abc" \
-H "Authorization: Bearer sk_your_secret_key_here"
Response
The API returns a detailed poster object:
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. Use this URL to display or download the QR code.
Physical location where the poster was placed, if provided.
ISO 8601 timestamp of when the poster was created.
ISO 8601 timestamp of when the poster was last updated.
Additional metadata about the poster placement, such as poster type, placement date, or custom fields.
Response Example
{
"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",
"updated_at": "2024-01-15T10:30:00Z",
"metadata": {
"poster_type": "standard",
"placement_date": "2024-01-15",
"dimensions": "11x17",
"notes": "Placed near main entrance"
}
}
Error Responses
Unauthorized - Invalid or missing API key{
"error": "Unauthorized",
"message": "Invalid or missing API key"
}
Not Found - The poster with the specified ID does not exist{
"error": "Not Found",
"message": "Poster not found"
}
Use Cases
Displaying Poster Details
Fetch poster information to display in a detail view:
async function getPosterDetails(posterId) {
try {
const response = await fetch(
`http://localhost:3000/api/v1/posters/${posterId}`,
{
headers: {
'Authorization': `Bearer ${API_KEY}`
}
}
);
if (response.status === 404) {
throw new Error('Poster not found');
}
if (!response.ok) {
throw new Error('Failed to fetch poster');
}
return await response.json();
} catch (error) {
console.error('Error fetching poster:', error);
throw error;
}
}
Downloading QR Code
Get the QR code URL and download it:
async function downloadPosterQRCode(posterId) {
const poster = await getPosterDetails(posterId);
// Use the qr_code_url to download or display the QR code
const qrCodeUrl = poster.qr_code_url;
// Example: Open in new window
window.open(qrCodeUrl, '_blank');
// Or download it
const response = await fetch(qrCodeUrl);
const blob = await response.blob();
const url = window.URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = `poster-${posterId}-qr.png`;
a.click();
}
Building Poster Detail Component
Create a React component to display poster details:
async function PosterDetail({ posterId }) {
const [poster, setPoster] = useState(null);
const [loading, setLoading] = useState(true);
useEffect(() => {
async function fetchPoster() {
try {
const response = await fetch(
`http://localhost:3000/api/v1/posters/${posterId}`,
{
headers: {
'Authorization': `Bearer ${API_KEY}`
}
}
);
if (response.ok) {
const data = await response.json();
setPoster(data);
}
} catch (error) {
console.error('Error:', error);
} finally {
setLoading(false);
}
}
fetchPoster();
}, [posterId]);
if (loading) return <div>Loading...</div>;
if (!poster) return <div>Poster not found</div>;
return (
<div>
<h1>Poster {poster.id}</h1>
<p>Location: {poster.location || 'Not specified'}</p>
<p>Created: {new Date(poster.created_at).toLocaleDateString()}</p>
<img src={poster.qr_code_url} alt="QR Code" />
</div>
);
}
Best Practices
- Cache poster data - Poster information doesn’t change frequently
- Handle 404 errors - Always check if the poster exists
- Use QR code URLs - The QR code URL can be used directly in img tags or downloaded
- Track locations - Use the location field to organize posters geographically
- Link to impressions - Use poster IDs to filter impressions and track scan rates
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.
The response is of type object.
