API Documentation

Complete API documentation for QR code generation, analytics, and management. Build powerful integrations with our RESTful API.

Quick Start

Get started with our API in minutes

1. Get Your API Key

Sign up for a Pro plan to get your API key from the dashboard.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://theqrcode.io/api/v1/qr-codes

2. Create Your First QR Code

Use our simple API to generate QR codes programmatically.

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "url", "content": "https://example.com"}' \
  https://theqrcode.io/api/v1/qr-codes

API Features

Powerful features for developers and integrations

RESTful API

Clean, intuitive REST API following industry standards with comprehensive documentation.

API Key Authentication

Secure API key-based authentication with rate limiting and usage tracking.

High Performance

Lightning-fast API responses with global CDN and optimized infrastructure.

Enterprise Security

Bank-level security with encryption, audit logs, and compliance standards.

Real-time Analytics

Access comprehensive analytics data through our powerful analytics API endpoints.

Webhook Support

Real-time notifications for QR code events with configurable webhook endpoints.

API Endpoints

Complete reference for all available API endpoints

POST/api/v1/qr-codes
Pro

Create a new QR code

Request Example

{
  "name": "My QR Code",
  "type": "url",
  "content": "https://example.com",
  "settings": {
    "size": 256,
    "color": {
      "dark": "#000000",
      "light": "#FFFFFF"
    },
    "frame": {
      "style": "square",
      "color": "#000000",
      "size": 20
    }
  },
  "isDynamic": false
}
Request Parameters
namestringRequired

Display name for the QR code

typestringRequired

QR code type (url, text, wifi, contact, email, sms, vcard)

contentstringRequired

The content to encode in the QR code

settingsobject

QR code appearance settings

settings.sizenumber

QR code size in pixels (default: 256)

settings.colorobject

Color settings for the QR code

settings.color.darkstring

Dark color (hex code, default: #000000)

settings.color.lightstring

Light color (hex code, default: #FFFFFF)

settings.frameobject

Frame settings for the QR code

settings.frame.stylestring

Frame style (square, circle, rounded)

settings.frame.colorstring

Frame color (hex code)

settings.frame.sizenumber

Frame size in pixels

isDynamicboolean

Whether the QR code can be updated after creation (default: false)

Response Example

{
  "id": "qr_123456789",
  "name": "My QR Code",
  "type": "url",
  "content": "https://example.com",
  "shortUrl": null,
  "settings": {
    "size": 256,
    "color": {
      "dark": "#000000",
      "light": "#FFFFFF"
    }
  },
  "isDynamic": false,
  "qrImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
GET/api/v1/qr-codes
Pro

List all QR codes with pagination and filtering

Request Example

{
  "query": "?page=1&limit=20&type=url&isDynamic=false"
}
Request Parameters
pagenumber

Page number for pagination (default: 1)

limitnumber

Number of items per page (default: 20, max: 100)

typestring

Filter by QR code type (url, text, wifi, contact, email, sms, vcard)

isDynamicboolean

Filter by dynamic QR codes (true/false)

searchstring

Search by QR code name or content

sortstring

Sort field (createdAt, updatedAt, name, scanCount)

orderstring

Sort order (asc, desc, default: desc)

Response Example

{
  "data": [
    {
      "id": "qr_123456789",
      "name": "My QR Code",
      "type": "url",
      "content": "https://example.com",
      "shortUrl": null,
      "settings": {
        "size": 256
      },
      "isDynamic": false,
      "scanCount": 42,
      "lastScanned": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}
GET/api/v1/qr-codes/{id}
Pro

Get specific QR code details with recent scans

Request Example

{}

Response Example

{
  "id": "qr_123456789",
  "name": "My QR Code",
  "type": "url",
  "content": "https://example.com",
  "shortUrl": null,
  "settings": {
    "size": 256
  },
  "isDynamic": false,
  "scanCount": 42,
  "lastScanned": "2024-01-15T10:30:00Z",
  "recentScans": [
    {
      "id": "scan_123",
      "scannedAt": "2024-01-15T10:30:00Z",
      "device": "mobile",
      "country": "US",
      "browser": "Chrome",
      "os": "iOS"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
PUT/api/v1/qr-codes/{id}
Pro

Update QR code name, content, or settings

Request Example

{
  "name": "Updated QR Code",
  "content": "https://updated-example.com",
  "settings": {
    "size": 512,
    "color": {
      "dark": "#FF0000",
      "light": "#FFFFFF"
    }
  }
}
Request Parameters
namestring

Updated display name for the QR code

contentstring

Updated content to encode in the QR code

settingsobject

Updated QR code appearance settings

settings.sizenumber

Updated QR code size in pixels

settings.colorobject

Updated color settings for the QR code

settings.color.darkstring

Updated dark color (hex code)

settings.color.lightstring

Updated light color (hex code)

settings.frameobject

Updated frame settings for the QR code

settings.frame.stylestring

Updated frame style (square, circle, rounded)

settings.frame.colorstring

Updated frame color (hex code)

settings.frame.sizenumber

Updated frame size in pixels

Response Example

{
  "id": "qr_123456789",
  "name": "Updated QR Code",
  "type": "url",
  "content": "https://updated-example.com",
  "shortUrl": null,
  "settings": {
    "size": 512,
    "color": {
      "dark": "#FF0000",
      "light": "#FFFFFF"
    }
  },
  "isDynamic": false,
  "qrImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:00:00Z"
}
DELETE/api/v1/qr-codes/{id}
Pro

Delete a QR code and all associated data

Request Example

{}

Response Example

null
POST/api/v1/qr-codes/bulk
Pro

Create multiple QR codes in a single request (up to 100)

Request Example

{
  "qrCodes": [
    {
      "name": "Product 1 QR",
      "type": "url",
      "content": "https://example.com/product1",
      "settings": {
        "size": 256,
        "color": {
          "dark": "#000000",
          "light": "#FFFFFF"
        }
      },
      "isDynamic": false
    },
    {
      "name": "Product 2 QR",
      "type": "url",
      "content": "https://example.com/product2",
      "settings": {
        "size": 256,
        "color": {
          "dark": "#0000FF",
          "light": "#FFFFFF"
        }
      },
      "isDynamic": true
    }
  ]
}
Request Parameters
qrCodesarrayRequired

Array of QR codes to create (max 100)

qrCodes[].namestringRequired

Display name for the QR code

qrCodes[].typestringRequired

QR code type (url, text, wifi, contact, email, sms, vcard)

qrCodes[].contentstringRequired

The content to encode in the QR code

qrCodes[].settingsobject

QR code appearance settings

qrCodes[].settings.sizenumber

QR code size in pixels (default: 256)

qrCodes[].settings.colorobject

Color settings for the QR code

qrCodes[].isDynamicboolean

Whether the QR code can be updated after creation (default: false)

Response Example

{
  "created": [
    {
      "id": "qr_123456789",
      "name": "Product 1 QR",
      "type": "url",
      "content": "https://example.com/product1",
      "shortUrl": null,
      "settings": {
        "size": 256,
        "color": {
          "dark": "#000000",
          "light": "#FFFFFF"
        }
      },
      "isDynamic": false,
      "qrImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "qr_987654321",
      "name": "Product 2 QR",
      "type": "url",
      "content": "https://example.com/product2",
      "shortUrl": "https://qr.io/abc123",
      "settings": {
        "size": 256,
        "color": {
          "dark": "#0000FF",
          "light": "#FFFFFF"
        }
      },
      "isDynamic": true,
      "qrImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
      "createdAt": "2024-01-15T10:30:01Z",
      "updatedAt": "2024-01-15T10:30:01Z"
    }
  ],
  "errors": [],
  "summary": {
    "total": 2,
    "successful": 2,
    "failed": 0
  }
}
DELETE/api/v1/qr-codes/bulk
Pro

Delete multiple QR codes in a single request (up to 100)

Request Example

{
  "qrCodeIds": [
    "qr_123456789",
    "qr_987654321",
    "qr_111222333"
  ]
}
Request Parameters
qrCodeIdsarrayRequired

Array of QR code IDs to delete (max 100)

Response Example

{
  "deleted": 2,
  "notFound": [
    "qr_111222333"
  ],
  "summary": {
    "total": 3,
    "deleted": 2,
    "notFound": 1
  }
}
GET/api/v1/analytics
Pro

Get comprehensive analytics data

Request Example

{
  "query": "?qrCodeId=qr_123&timeRange=30d&includeScans=true"
}
Request Parameters
qrCodeIdstring

Specific QR code ID to get analytics for

timeRangestring

Time range for analytics (1h, 1d, 7d, 30d, 90d, 1y, default: 30d)

includeScansboolean

Include individual scan data in response (default: false)

startDatestring

Start date for custom range (ISO 8601 format)

endDatestring

End date for custom range (ISO 8601 format)

groupBystring

Group analytics by (hour, day, week, month)

timezonestring

Timezone for date grouping (default: UTC)

Response Example

{
  "summary": {
    "totalScans": 1250,
    "totalQRCodes": 5,
    "timeRange": "30d",
    "startDate": "2024-01-01T00:00:00Z",
    "endDate": "2024-01-31T23:59:59Z",
    "uniqueVisitors": 850,
    "avgScansPerQR": 250,
    "mostActiveDay": "2024-01-15"
  },
  "breakdowns": {
    "devices": {
      "mobile": 800,
      "desktop": 300,
      "tablet": 150
    },
    "countries": {
      "US": 600,
      "CA": 300,
      "UK": 200,
      "DE": 150
    },
    "browsers": {
      "Chrome": 700,
      "Safari": 300,
      "Firefox": 150,
      "Edge": 100
    },
    "os": {
      "iOS": 400,
      "Android": 400,
      "Windows": 300,
      "macOS": 150
    }
  },
  "distributions": {
    "hourly": [
      {
        "hour": 0,
        "count": 10
      },
      {
        "hour": 1,
        "count": 5
      }
    ],
    "weekly": [
      {
        "day": 0,
        "count": 200
      },
      {
        "day": 1,
        "count": 180
      }
    ]
  },
  "dailyScans": [
    {
      "date": "2024-01-01",
      "count": 25
    },
    {
      "date": "2024-01-02",
      "count": 30
    }
  ],
  "topQRCodes": [
    {
      "id": "qr_123",
      "name": "Main QR Code",
      "type": "url",
      "scanCount": 500,
      "isDynamic": true
    }
  ]
}
GET/api/v1/api-keys
Pro

List all API keys for the authenticated user

Request Example

{}

Response Example

{
  "data": [
    {
      "id": "ak_123456789",
      "name": "Production API Key",
      "permissions": [
        "qr:read",
        "qr:write",
        "analytics:read"
      ],
      "rateLimit": 1000,
      "isActive": true,
      "lastUsedAt": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}
POST/api/v1/api-keys
Pro

Create a new API key with custom permissions

Request Example

{
  "name": "Development API Key",
  "permissions": [
    "qr:read",
    "qr:write"
  ],
  "expiresAt": "2024-12-31T23:59:59Z"
}
Request Parameters
namestringRequired

Display name for the API key

permissionsarrayRequired

Array of permissions (qr:read, qr:write, analytics:read, webhooks:manage)

expiresAtstring

Expiration date for the API key (ISO 8601 format)

rateLimitnumber

Custom rate limit (requests per hour, max based on plan)

descriptionstring

Optional description for the API key

Response Example

{
  "id": "ak_987654321",
  "name": "Development API Key",
  "apiKey": "qrc_1234567890abcdef...",
  "permissions": [
    "qr:read",
    "qr:write"
  ],
  "rateLimit": 1000,
  "expiresAt": "2024-12-31T23:59:59Z",
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00Z"
}
GET/api/v1/webhooks
Pro

List all webhooks

Request Example

{}

Response Example

{
  "data": [
    {
      "id": "wh_123456789",
      "name": "Scan Notifications",
      "url": "https://myapp.com/webhooks/qr-scans",
      "events": [
        "scan.created",
        "scan.updated"
      ],
      "isActive": true,
      "lastTriggeredAt": "2024-01-15T10:30:00Z",
      "failureCount": 0,
      "eventCount": 150,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}
POST/api/v1/webhooks
Pro

Create a new webhook

Request Example

{
  "name": "QR Code Events",
  "url": "https://myapp.com/webhooks/qr-events",
  "events": [
    "qr.created",
    "qr.updated",
    "qr.deleted"
  ]
}
Request Parameters
namestringRequired

Display name for the webhook

urlstringRequired

Webhook endpoint URL (must be HTTPS)

eventsarrayRequired

Array of events to subscribe to (qr.created, qr.updated, qr.deleted, scan.created, scan.updated)

secretstring

Custom webhook secret for signature verification

descriptionstring

Optional description for the webhook

retryPolicyobject

Custom retry policy settings

retryPolicy.maxAttemptsnumber

Maximum retry attempts (default: 3)

retryPolicy.backoffMultipliernumber

Backoff multiplier for retries (default: 2)

Response Example

{
  "id": "wh_987654321",
  "name": "QR Code Events",
  "url": "https://myapp.com/webhooks/qr-events",
  "events": [
    "qr.created",
    "qr.updated",
    "qr.deleted"
  ],
  "secret": "whsec_1234567890abcdef...",
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00Z"
}

Webhooks

Get real-time notifications when QR codes are created, updated, or scanned. Perfect for building reactive systems and keeping your data in sync.

Available Events

QR Code Events

Available
qr.createdNew QR code created
qr.updatedQR code content updated
qr.deletedQR code deleted

Scan Events

Available
scan.createdQR code scanned
scan.updatedScan data updated

Getting Started

1. Create a Webhook

POST /api/v1/webhooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "My Webhook",
  "url": "https://myapp.com/webhooks/qr-events",
  "events": ["qr.created", "scan.created"]
}

2. Handle Incoming Events

// Verify webhook signature
const signature = req.headers['x-webhook-signature'];
const payload = JSON.stringify(req.body);

// Generate expected signature
const expectedSignature = hmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (signature === expectedSignature) {
  // Process webhook event
  const event = req.body;
  console.log('Event type:', event.type);
  console.log('Data:', event.data);
}

Requirements

  • •HTTPS endpoint required: All webhook URLs must use HTTPS for security
  • •Fast response expected: Your endpoint should respond with 2xx status within 10 seconds
  • •Retry policy: Failed webhooks will be retried up to 3 times with exponential backoff

Rate Limits & Pricing

Transparent pricing and rate limits for API usage

Free

$0/month
No API access
  • No API access
  • Dashboard only

Starter

$9/month
No API access
  • No API access
  • Dashboard only
API Access

Pro

$29/month
Full API access
  • 5,000 requests/hour
  • QR Code API
  • Analytics API
  • Webhooks
  • API Key management
  • Priority support

Ready to Start Building?

Get your API key and start integrating QR codes into your applications today.

Get API AccessContact Sales