API Integration Quick Start

Before You Start

You will need a QRZone account with API access (available on Pro and Enterprise plans) and an API key, which you can generate from your dashboard under Settings then API Keys. All API requests require the API key in the Authorization header.

Authentication

All API requests must include your API key in the Authorization header as a Bearer token. Example: Authorization: Bearer qrz_live_abc123.... API keys have the same permissions as the user who created them. For production integrations, create a dedicated service account with minimal required permissions.

Your First API Call

Generate a Dynamic QR Code

The POST /v1/codes endpoint creates a new dynamic QR code. The minimum required field is destination -- the URL the code should redirect to. The API returns the code ID, short URL, and download links for the QR code image in SVG, PNG, and PDF formats.

Request body example:

{
  "destination": "https://yoursite.com/landing",
  "name": "Homepage Campaign Q1",
  "style": {
    "foregroundColor": "#1a1a2e",
    "backgroundColor": "#ffffff",
    "cornerStyle": "rounded"
  }
}

Retrieving Scan Analytics

The GET /v1/codes/:id/analytics endpoint returns scan data for a specific code. Query parameters allow filtering by date range, geographic region, and device type. The response includes total scans, unique scanners, time series data, and top locations.

Bulk Code Generation

The POST /v1/codes/batch endpoint accepts an array of up to 1,000 code definitions in a single request. Each definition can have its own destination, name, and style. The API returns a batch ID that you can poll for completion status. Batch operations are processed asynchronously and typically complete within 30 seconds for 1,000 codes.

Webhooks

Configure webhooks to receive real-time notifications for scan events, code updates, and campaign milestones. Webhook payloads include the full scan event data (timestamp, location, device, code ID). This enables real-time dashboards, CRM updates, and automated workflows triggered by QR scans.

Rate Limits

API rate limits depend on your plan: Free (100 requests/hour), Pro (1,000 requests/hour), Enterprise (10,000 requests/hour or custom). Rate limit headers are included in every response: X-RateLimit-Remaining and X-RateLimit-Reset. Implement exponential backoff for 429 responses.

SDKs and Libraries

Official SDKs are available for Node.js (npm install @qrzone/sdk), Python (pip install qrzone), and Ruby (gem install qrzone). Community-maintained SDKs are available for Go, PHP, and Java. All SDKs handle authentication, rate limiting, and response parsing automatically.

Next Steps

After generating your first code via the API, explore smart routing configuration via the /v1/codes/:id/routing endpoint, landing page customization via the /v1/pages endpoint, and team management via the /v1/teams endpoint. Full API reference documentation is available at /docs/api-reference.