Upload Sessions
Upload sessions are the core building block of Apertur. They define how, when, and where photos are collected from end-users via QR codes.
What Is a Session?
A session is a time-limited, single-use link that allows an end-user to upload one or more photos from their mobile device. Each session has its own QR code, configuration, and delivery destination.
When you create a session via the API, Apertur generates a unique URL and QR code. The end-user scans the code, takes or selects photos, and the images are delivered to your configured destination (webhook, S3, Google Drive, etc.).
Sessions automatically expire after a configurable duration, ensuring that upload links don't remain active indefinitely.
Configuration Options
When creating a session, you can customise its behaviour with the following parameters:
| Parameter | Type | Description |
|---|---|---|
| expires_in | integer | Time in seconds until the session expires. Default: 3600 (1 hour). Max: 604800 (7 days). |
| max_images | integer | Maximum number of images the user can upload. Default: 10. Max: 50. |
| allowed_mime_types | string[] | Restrict accepted file types. E.g. ["image/jpeg", "image/png"]. Defaults to all image types. |
| password | string | Require a password before the user can upload. The password is hashed server-side. |
| delivery_mode | string | Where to deliver photos: webhook, s3, gdrive, dropbox, onedrive, ftp, azure_blob, or webdav. |
| tags | object | Arbitrary key-value metadata attached to the session and included in webhook payloads. |
curl -X POST https://api.apertur.ca/v1/sessions \
-H "Authorization: Bearer aptr_live_xxxx" \
-H "Content-Type: application/json" \
-d '{
"delivery_mode": "webhook",
"webhook_url": "https://your-app.com/webhook",
"expires_in": 7200,
"max_images": 3,
"allowed_mime_types": ["image/jpeg", "image/png"],
"password": "secret123",
"tags": { "claim_id": "CLM-4521" }
}'QR Code Best Practices
The QR code is how end-users access the upload page. Follow these guidelines for the best experience.
Size & Resolution
Generate QR codes at a minimum of 200x200 pixels for screen display, or 300 DPI for print. Larger codes scan more reliably at a distance.
Placement & Contrast
Place QR codes on a light background with high contrast. Avoid placing them over busy images or near other visual noise. Leave a quiet zone (white border) of at least 4 modules around the code.
Printing Tips
- Use matte finishes to avoid glare that interferes with scanning.
- Test printed codes under the same lighting conditions as the final environment.
- Include a short instruction like "Scan to upload photos" near the code.
- Consider adding your logo to the centre of the QR code (with error correction level H).
Digital Display
When displaying QR codes on screens (tablets, kiosks, monitors), ensure the screen brightness is high enough and there is no screen protector glare. For very large screens, increase the QR code size proportionally.
Session Lifecycle
A session moves through several states during its lifetime:
Session has been created but no photos have been uploaded yet.
At least one photo has been uploaded. The session is still accepting more photos.
All photos have been uploaded (max_images reached) or the session was manually completed. Delivery is in progress or finished.
The session has passed its expiration time. No more uploads are accepted.
You can query a session's current status at any time using GET /api/v1/sessions/:id. Webhook and event notifications are also sent on each status change.
Real-Time Monitoring
Apertur provides several ways to monitor your sessions in real time.
Dashboard
Your project dashboard shows all active sessions with their current status, upload count, and time remaining. Sessions update in real time — no need to refresh.
Long Polling
For server-side integrations, you can use long polling to wait for session updates without repeatedly hitting the API.
curl https://api.apertur.ca/v1/sessions/sess_01HX.../poll \ -H "Authorization: Bearer aptr_live_xxxx" \ -H "Accept: application/json"
See the long polling documentation for implementation details.
Related Articles
Was this article helpful?
Need more help? Contact our support team.