Integrate QR Code Generation with the QR Penguin API

We're excited to announce the release of the QR Penguin API - a powerful REST API that allows you to programmatically create, manage, and track QR codes directly from your applications. Whether you're building a marketing platform, event management system, or custom business solution, our API provides everything you need to integrate professional QR code functionality.

You can view our API documentation here, which includes interactive examples and detailed schema definitions. In this guide, we'll walk you through the key features of the QR Penguin API and show you how to get started with integrating QR code generation into your applications.

Getting Started with API Authentication

To use the QR Penguin API, you'll first need to generate an API token from your account dashboard. Navigate to your account settings and find the API Tokens section. Here you can create a new token, give it a descriptive name, and copy it for use in your applications.

Once you have your API token, include it in the Authorization header of your requests using the Bearer token format. All API endpoints are accessible at https://qrpenguin.com/api/v1/ and require authentication.

Creating QR Codes via API

The API supports creating all types of QR codes that you can generate through our web interface - from simple website QR codes to complex vCard and WiFi QR codes. You can customize every aspect of your QR code including patterns, colors, eyes, backgrounds, logos, and frames.

Simple Website QR Code Example

Here's a basic example of creating a website QR code with custom styling:

POST https://qrpenguin.com/api/v1/qr_codes
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "data": {
    "active_type": "website",
    "website": {
      "website": "https://yourcompany.com"
    }
  },
  "options": {
    "name": "Company Website QR",
    "static_yn": false,
    "error_correction": "h",
    "domain": "qrpenguin.com",
    "gps": true
  },
  "style": {
    "pattern": {
      "colour_type": "single",
      "pattern_type": "dot",
      "single_colour": "#000000"
    },
    "eyes": {
      "eye_type": "single",
      "eye_ball": "circle",
      "eye_frame": "circle",
      "eye_ball_colour": "#000000",
      "eye_frame_colour": "#000000",
      "eye_ball_rotation": 0,
      "eye_frame_rotation": 0
    },
    "background": {
      "background_type": "colour",
      "background_colour": "#ffffff"
    }
  }
}

Supported QR Code Types

The API supports all QR code types including: Website, Plain Text, Email, vCard Contact, SMS, Location, Phone Call, App Download, WiFi, Calendar Event, and Dynamic QR codes for text and vCards. Each type has specific data fields that you can populate according to your needs.

Advanced Styling Options

One of the most powerful features of the QR Penguin API is the ability to fully customize the appearance of your QR codes. You can apply gradients, custom patterns, unique eye designs, add logos, and even include frames with text.

Pattern Styles

Choose from over 15 different pattern styles including: dot, circle, triangle, rhombus, star, cross, ring, and more. You can apply single colors or create beautiful gradients with multiple colors and directions.

Custom Eye Designs

The three positioning eyes of a QR code can be customized independently. Choose different shapes for the eye ball and eye frame, apply unique colors, and even rotate them for a distinctive look. Available styles include rounded, circle, square, star, plus, and eye shaped designs.

Adding Logos and Frames

Enhance brand recognition by adding your company logo to the center of QR codes. The API accepts base64-encoded images and allows you to control the logo size and background transparency. You can also add frames with custom text, colors, and fonts to make your QR codes stand out.

Managing Your QR Codes

The API provides full CRUD (Create, Read, Update, Delete) operations for managing your QR codes. You can list all your QR codes with powerful filtering and sorting options, retrieve individual QR codes by ID, update existing QR codes, and archive or delete them when no longer needed.

Listing and Filtering QR Codes

The GET /api/v1/qr_codes endpoint supports comprehensive filtering and sorting. You can search by name, filter by type (Dynamic, Static, or Archived), filter by destination type (website, vcard, email, etc.), filter by tags, and sort by Name, Created date, Updated date, or Scan count. The API also supports pagination with customizable limits.

GET https://qrpenguin.com/api/v1/qr_codes?query=website&type=Dynamic&sort=Scans&limit=50
Authorization: Bearer YOUR_API_TOKEN

Updating QR Codes

For dynamic QR codes, you can update the destination URL, styling, and other properties without changing the QR code image itself. This is particularly powerful for printed materials where you need to update the destination after distribution. Simply send a PUT request to /api/v1/qr_codes/{id} with the updated data.

Tracking Scans and Analytics

One of the most valuable features of the QR Penguin API is the ability to retrieve detailed scan analytics. The scans endpoint provides comprehensive data about when and where your QR codes are being scanned, helping you understand user engagement and make data-driven decisions.

Retrieving Scan Data

The GET /api/v1/scans endpoint returns detailed information about each scan including the timestamp, location data (city, region, country), operating system, the QR code name, and the QR code type. This data is automatically collected when anyone scans one of your QR codes.

Advanced Filtering Options

Filter scan data by date range using start_at and end_at parameters (defaults to the last 29 days). You can also filter by specific QR code destinations, tags, or names. The API returns aggregate statistics including total scans, unique scans, and the number of selected QR codes in your query.

GET https://qrpenguin.com/api/v1/scans?start_at=2024-12-01&end_at=2024-12-20&destinations[]=website&destinations[]=vcard
Authorization: Bearer YOUR_API_TOKEN

Using Custom Domains

For dynamic QR codes, you can specify custom domains that you've configured in your account. This allows you to use your own branded domain for QR code redirects, enhancing trust and brand recognition. Make sure to add and verify your domain in the account settings before using it in API requests.

Error Handling and Best Practices

The API uses standard HTTP status codes to indicate success or failure. A 201 status indicates successful creation, 200 for successful retrieval or updates, 401 for authentication errors, 404 for not found resources, and 422 for validation errors. Always check the status code and handle errors appropriately in your application.

API Rate Limits

While we don't enforce strict rate limits for authenticated API requests, we recommend implementing reasonable retry logic with exponential backoff in case of temporary errors. Keep your API tokens secure and never expose them in client-side code or public repositories.

Use Cases and Integration Examples

The QR Penguin API opens up countless possibilities for integration. Here are some popular use cases:

Event Management: Automatically generate unique QR codes for event tickets, badges, or check-in systems
Marketing Automation: Create personalized QR codes for each customer or campaign with dynamic destinations
Product Packaging: Generate product-specific QR codes that link to documentation, tutorials, or authentication
Restaurant Menus: Create and update digital menu QR codes without reprinting table displays
Real Estate: Generate property listing QR codes with detailed information and virtual tours
Inventory Management: Create QR codes for asset tracking and product identification

Getting Help and Documentation

For complete API documentation including detailed schema definitions, request/response examples, and authentication details, visit our interactive API documentation. If you encounter any issues or have questions about the API, our support team is here to help at support@qrpenguin.com.

We're excited to see what you build with the QR Penguin API! Start generating your first QR codes today and unlock the full potential of programmatic QR code creation and management.

Sample our QR Code Generator for Yourself

No sign up required

Try the Generator

Sign up to QR Penguin

Access 2 dynamic QR codes completely free - no subscription trials or payment required!