QR Code Generation

API reference for generating QR codes linked to platform entities.

Generate QR codes linked to platform entities -- properties, bookings, payments, agents, partners, and principals. Each QR code encodes a URL that resolves to the appropriate entity page in your application.

Generate a QR code

POST /api/v1/qr

Scope: storage:upload

Request body

Field	Type	Required	Description
entityType	string	Yes	Entity type for the QR target (see below)
entityId	string	Yes	ID of the entity
options.size	string	No	QR size: small, medium, or large. Default from processor config (300px)
options.errorCorrection	string	No	Error correction level: L, M, Q, or H. Default: M
options.foreground	string	No	Foreground color (hex, e.g. #000000)
options.background	string	No	Background color (hex, e.g. #FFFFFF)
options.includeUtm	boolean	No	Whether to append UTM parameters to the target URL
options.utmSource	string	No	UTM source parameter
options.utmMedium	string	No	UTM medium parameter
options.utmCampaign	string	No	UTM campaign parameter

Entity types

Type	Description
PROPERTY	Property listing
BOOKING	Booking record
PAYMENT	Payment transaction
AGENT	Agent profile
PARTNER	Partner profile
PRINCIPAL	Principal (landlord) profile

Response

{
  "success": true,
  "data": {
    "qrDataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSU...",
    "targetUrl": "https://app.example.com/properties/prop_123",
    "entityType": "PROPERTY",
    "entityId": "prop_123"
  }
}

Field	Type	Description
qrDataUrl	string	Base64-encoded QR code image (PNG or SVG based on processor config)
targetUrl	string	The URL encoded in the QR code
entityType	string	The entity type
entityId	string	The entity ID

Processor configuration

The QR processor controls default generation settings. See Service Processors for the full API pattern.

Setting	Default	Description
defaultSize	300	Default QR code size in pixels
defaultFormat	"png"	Default output format: png or svg
maxBatchSize	100	Maximum items per batch request

Examples

Generate a property QR code

curl

curl -X POST https://api.platformxe.com/api/v1/qr \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "entityType": "PROPERTY",
    "entityId": "prop_123",
    "options": {
      "size": "large",
      "errorCorrection": "H",
      "includeUtm": true,
      "utmSource": "flyer",
      "utmCampaign": "q2-2026"
    }
  }'

TypeScript SDK

import { PlatformXe } from '@caldera/platformxe-sdk';

const px = new PlatformXe({ apiKey: 'pxk_live_your_api_key_here' });

const qr = await px.qr.generate({
  entityType: 'PROPERTY',
  entityId: 'prop_123',
  options: {
    size: 'large',
    errorCorrection: 'H',
    includeUtm: true,
    utmSource: 'flyer',
    utmCampaign: 'q2-2026',
  },
});

console.log(qr.targetUrl);
// "https://app.example.com/properties/prop_123?utm_source=flyer&utm_campaign=q2-2026"

Python SDK

from platformxe import PlatformXe

px = PlatformXe(api_key="pxk_live_your_api_key_here")

qr = px.qr.generate({
    "entityType": "PROPERTY",
    "entityId": "prop_123",
    "options": {
        "size": "large",
        "errorCorrection": "H",
        "includeUtm": True,
        "utmSource": "flyer",
        "utmCampaign": "q2-2026"
    }
})

print(qr["targetUrl"])

Generate with custom colors

const qr = await px.qr.generate({
  entityType: 'AGENT',
  entityId: 'agt_456',
  options: {
    foreground: '#102a4a',
    background: '#FFFFFF',
    size: 'medium',
  },
});

Error responses

Code	Description
BAD_REQUEST	Invalid entity type, missing entity ID, or invalid options
FORBIDDEN	API key does not have the storage:upload scope
SERVICE_DISABLED	QR processor is disabled for this organization
RATE_LIMITED	Rate limit exceeded