QRStuff API Integration

Getting Started

Before you begin integrating with the QRStuff API, ensure you have completed the following setup requirements to enable seamless integration:

1. Active Subscription: You must have an active QRStuff subscription account. The API access is included with all paid subscription plans. Enterprise plans offer higher rate limits and priority support for high-volume applications.
2. API Credentials: Obtain your unique API key and authentication token from your account dashboard under the API section. These credentials are required for all authenticated API requests and should be kept secure.
3. Base URL Configuration: All API requests should be made to the base endpoint https://api.qrstuff.com. Ensure your application can make HTTPS requests to this domain without firewall or proxy restrictions.
4. Authentication Setup: Include your API credentials in the Authorization header for all authenticated endpoints. Use Bearer token authentication format to ensure secure communication between your application and the API.
5. Content Type Headers: All requests should be sent with Content-Type: application/json header, and all responses will be returned in JSON format for easy parsing and integration with modern applications.
6. Rate Limit Awareness: Be aware of rate limiting based on your subscription tier. Standard plans support typical application usage, while Enterprise plans offer significantly higher rate limits for high-volume, mission-critical applications requiring thousands of requests per hour.

Authentication Example

Include your API key in the Authorization header for all authenticated requests. Here's a basic example of how to structure your API calls:

                
                    curl -X POST 'https://api.qrstuff.com/api/projects' \
                    -H "Authorization: Bearer [your_api_key]" \
                    -H "Content-Type: application/json" \
                    -d '{
                        "name": "Project Name"
                    }'
                
            

API Endpoints

Project Management Endpoints

Organize and manage your QR codes efficiently with comprehensive project-based organization. Projects serve as containers that help you categorize and manage QR codes by campaign, client, department, or any logical grouping that fits your workflow:

• Create Project (POST /projects): Initialize a new project container for organizing related QR codes. Specify project name, description, default settings, and any custom metadata fields your application requires.
• Get Project (GET /projects/{id}): Retrieve detailed information about a specific project including all settings, metadata, creation date, last modified date, total QR code count, and associated analytics summaries.
• Update Project (PUT /projects/{id}): Modify project details, update settings and configuration options, change project names or descriptions, and adjust default QR code generation parameters for the project.
• List Projects (GET /projects): Get a paginated list of all your projects with flexible filtering options, sorting by name or date, search capabilities, and customizable page sizes for efficient data retrieval.
• Delete Project (DELETE /projects/{id}): Remove projects with options to either delete or archive associated QR codes. Supports soft deletion with configurable retention periods for data recovery.
• Restore Deleted Projects (POST /projects/{id}/restore): Recover accidentally deleted projects within the retention period, restoring all associated QR codes and settings to their previous state.

QR Code Operations

Core functionality for creating, managing, and manipulating QR codes programmatically:

• Create QR Code (POST /qr-codes): Generate a new QR code by specifying the data type (from 40+ supported types), content data, design customizations, error correction level, and target project. Returns the QR code ID, download URL, and preview link.
• Get QR Codes (GET /projects/{id}/qr-codes): Retrieve all QR codes from a specific project with pagination support, filtering by type or date range, sorting options, and detailed metadata for each QR code including scan counts and last scan date.
• Update QR Code (PUT /qr-codes/{id}): Modify existing QR code content, update destination URLs for dynamic QR codes, change design elements, adjust settings, and update metadata without requiring reprinting.
• Transfer QR Codes (POST /api/qrcodes/anonymous-transfer): Transfer single or multiple QR codes between projects for better organization. Supports bulk transfers with a single API call, maintaining all analytics and history data.
• Delete QR Code (DELETE /qr-codes/{id}): Remove QR codes with optional soft delete, supporting recovery within retention period and preserving historical analytics data for reporting purposes.

Batch Processing Operations

Powerful bulk operations designed for enterprise-scale QR code management, enabling efficient handling of large deployments:

• Batch Submit (POST /api/batch/submit): Initiate the processing of a large batch file containing data for multiple QR codes. This queues the job for generation and validation on the server.
• Batch Zip File Download (GET /api/qrcodes/{{qrcode_id}}/zip/download): Retrieve the final ZIP archive containing all generated QR code images for a specific, completed batch job.
• Batch Unpack (POST /api/batch/unpack): Extract all QR codes and data files from a previously completed batch archive. Ideal for integrating created codes directly into client systems or subsequent batch processes.
• Batch Update (POST /api/batch/update): Update properties across multiple QR codes simultaneously, such as applying new design templates, changing error correction levels, or updating metadata fields in bulk.

Analytics & Tracking Endpoints

Comprehensive analytics endpoints for understanding QR code performance and user engagement patterns. Access real-time and historical data to measure campaign effectiveness:

• Total Scans (GET /analytics/scans): Get cumulative scan counts for specific projects, individual QR codes, or your entire account. Supports date range filtering and comparison periods for trend analysis.
• Device Wise Scans (GET /analytics/scans/devices): Detailed breakdown of scans by device type and operating system including iOS (iPhone, iPad), Android (various manufacturers), Desktop (Windows, Mac, Linux), tablets, and other devices with version information.
• Geographic Analytics (GET /analytics/location): Identify where your QR codes are being scanned with country-level, state/province-level, and city-level data. Includes coordinates for mapping and visualization purposes.
• Top Performing Location (GET /analytics/top-location): Discover geographic regions with the highest engagement rates, helping you identify successful markets and optimize campaign targeting for future deployments.
• Top Performing Date (GET /analytics/top-date): Identify peak scanning days and specific dates with highest engagement. Useful for understanding campaign timing effectiveness and planning future launches.
• Time of Day Analysis (GET /analytics/time-of-day): Analyze scanning patterns throughout the day to understand when your audience is most engaged. Returns hourly breakdown data for optimizing content delivery timing.
• Unique Users (GET /analytics/unique-users): Track individual user engagement, identify return visitors versus new users, calculate engagement rates, and understand audience loyalty patterns over time.
• Country Chart Data (GET /analytics/charts/country): Get formatted data for generating visual country-wise scan distribution charts. Returns data ready for popular charting libraries like Chart.js, D3.js, or Highcharts.
• Time Chart Data (GET /analytics/charts/time): Retrieve time-series data for creating visual representations of scan patterns over hours, days, weeks, or months with customizable granularity.

File Management

Robust file handling system for QR codes that require hosted content like documents, images, media files, or any downloadable assets:

• Upload File (POST /files): Store files securely on QRStuff servers to be used with your QR codes. Supports PDFs, images (JPG, PNG, GIF), audio files (MP3, WAV), video files (MP4, MOV), and documents with automatic format validation and virus scanning.
• Get File (GET /files/{id}): Retrieve stored file information including public download URLs, file metadata (size, type, upload date), thumbnail URLs for images, and access statistics.
• List Files (GET /files): Browse all uploaded files with pagination, filtering by file type or upload date, search functionality, and sorting options for efficient file library management.
• Delete File (DELETE /files/{id}): Remove files that are no longer needed. The API will check if files are currently in use by any QR codes and prevent deletion to avoid breaking active codes.

Supported QR Code Types (40+ Data Formats)

Generate QR codes for an extensive variety of use cases and data types. Each type has specific parameters and formatting requirements detailed in the full API documentation:

Note: Each QR code type has specific parameter requirements and formatting rules. Consult the detailed API documentation at https://api.qrstuff.com/docs for complete specifications, example requests, and response formats for each type.

Best Practices

Use Dynamic QR Codes: Always generate dynamic QR codes through the API when possible. Dynamic QR codes allow you to update the destination URL or content without reprinting the physical QR code, track comprehensive analytics including scan counts and user demographics, A/B test different destinations, maintain better control over your marketing campaigns, and extend the lifespan of printed materials by avoiding obsolescence.

Implement Robust Error Handling: Always implement comprehensive error handling in your API integration. Check HTTP response status codes (200 for success, 400 for bad requests, 401 for authentication issues, 429 for rate limits, 500 for server errors), handle rate limits gracefully with exponential backoff strategies, implement retry logic for transient failures, log all errors with contextual information for debugging, and validate API responses before processing. The API returns descriptive error messages with specific error codes to help you troubleshoot issues quickly and efficiently.

Leverage Batch Operations: When working with multiple QR codes, always use batch endpoints for downloading, printing, and moving operations instead of making individual sequential requests. Batch operations reduce the total number of API calls significantly, improve overall performance and response times, ensure you stay within rate limits even for large operations, reduce network overhead and latency, and provide atomic operations where all items succeed or fail together, maintaining data consistency across your application.

Implement Smart Caching: Cache QR code images and relatively static project data appropriately to reduce unnecessary API calls and improve application performance. However, ensure analytics data is fetched fresh when needed for accurate real-time reporting and decision-making. Consider implementing a tiered caching strategy: cache QR code images indefinitely (they don't change), cache project metadata for 5-15 minutes, refresh analytics data every 1-5 minutes for dashboards, and invalidate caches when you make updates through the API. Use ETags and Last-Modified headers for efficient cache validation.

Security First Approach: Never expose your API keys in client-side JavaScript code, public repositories, or version control systems. Store API credentials securely using environment variables, encrypted configuration files, or dedicated secrets management systems like AWS Secrets Manager or HashiCorp Vault. Implement API key rotation periodically (every 90 days recommended), monitor API usage logs for suspicious activity or unexpected patterns, use HTTPS for all requests, implement request signing for additional security in sensitive applications, and restrict API access by IP address or domain when possible for enterprise deployments.

Use Cases & Real-World Examples

Event Management & Ticketing Platform

Integrate QR code generation for comprehensive event management including ticket distribution and attendee tracking. Create unique QR codes for each ticket purchase with encrypted attendee information, track attendance in real-time through scan analytics and check-in applications, manage multiple concurrent events using project organization with separate folders per event, implement VIP and general admission tiers with different QR code designs, send dynamic tickets via email that can be updated if event details change, generate check-in codes for staff and volunteers, update event information dynamically without reissuing tickets, gather valuable attendee insights including arrival times and engagement patterns, implement session tracking for multi-day conferences, and create post-event follow-up campaigns based on attendance data.

Inventory & Asset Management Systems

Build comprehensive inventory management and asset tracking systems with seamless QR code integration. Generate unique identification codes for each product, equipment piece, or asset in your organization, track item location and movement history through scan analytics and geographic data, maintain detailed digital records including purchase date, warranty information, maintenance schedules, and depreciation data, implement automated checkout/check-in systems for equipment lending, create hierarchical organization with projects representing warehouses, departments, or locations, use batch operations to generate codes for new inventory shipments efficiently, update asset information dynamically as items are serviced or relocated, integrate with existing ERP or inventory management software through webhooks, implement audit trails for compliance requirements, and generate reports on asset utilization and location history. Perfect for warehouses, retail operations, libraries, equipment rental businesses, and enterprise asset management.

Marketing Campaign Management & Analytics

Create sophisticated data-driven marketing campaigns with trackable QR codes for print materials, product packaging, outdoor advertising, and promotional items. Generate unique codes for different campaigns, channels, or demographic segments to track source attribution, update campaign destinations and landing pages without reprinting expensive materials, A/B test different landing pages or offers by rotating destinations for specific QR codes, measure campaign effectiveness through detailed geographic and temporal analytics showing exactly when and where engagement occurs, implement seasonal campaigns with scheduled content updates, track ROI by correlating scan data with conversion events, create personalized marketing experiences by encoding user identifiers, segment audiences based on scan behavior and location data, implement retargeting campaigns for users who scanned but didn't convert, and generate comprehensive reports showing campaign performance across all channels. Ideal for retail brands, consumer products, event promotions, and omnichannel marketing strategies.

Educational Content Distribution & Engagement

Enhance educational materials and learning experiences with QR codes linking to rich supplementary content, interactive resources, and assessment tools. Embed codes in textbooks, worksheets, and classroom posters that link to instructional videos, 3D models, audio pronunciations, or interactive simulations, track student engagement and resource usage through analytics to identify which materials are most effective, organize content by course, grade level, or subject using comprehensive project structures, update learning materials dynamically as curriculum evolves without replacing physical materials, create self-paced learning paths where students scan codes to access progressive content, implement formative assessments through QR-linked quizzes and surveys, provide differentiated instruction by linking to resources at various difficulty levels, enable parent involvement by providing codes that link to home learning activities, create interactive field trip experiences with location-based QR codes, and measure learning outcomes by correlating scan data with assessment results. Perfect for K-12 education, higher education, corporate training programs, and museum exhibits.

Restaurant & Hospitality Management

Implement modern contactless solutions for restaurants, hotels, and hospitality venues including digital menus, ordering systems, and guest services. Generate table-specific QR codes for contactless ordering and payment that reduce staff workload and improve table turnover rates, update menus in real-time without reprinting expensive physical menus, highlight daily specials or seasonal offerings dynamically, collect customer feedback through QR-linked forms immediately after dining experiences, implement loyalty program enrollment through scannable codes at checkout, provide multilingual menu options by detecting user device language preferences, track which menu items are viewed most frequently to optimize menu design, enable guests to access hotel services, room service, and concierge information via in-room QR codes, create virtual hotel tours for prospective guests, analyze customer preferences and ordering patterns through detailed scan analytics, implement contactless check-in/check-out procedures, and personalize guest experiences based on previous visit data. Enhance customer experience while gathering valuable business intelligence for operations optimization.