BrandCode API v1

Generate, edit, render, and track QR codes from your product.

BrandCode API uses bearer tokens, workspace-scoped permissions, test/live modes, idempotency keys for creation workflows, and usage logs for operational visibility.

Authentication

Authorization: Bearer bc_live_...
Idempotency-Key: customer-or-order-id

Tokens are shown once, stored hashed, scoped by workspace, and separated between test and live mode.

Downloads

OpenAPI spec Postman collection JavaScript SDK Python SDK PHP SDK

Scopes

qr:readqr:writeqr:deleteanalytics:readdestinations:readdestinations:writelanding_pages:readlanding_pages:writewebhooks:readwebhooks:write

Create dynamic QR via API Update destination via API Render QR via API Read scan analytics via API API use cases

POST/api/v1/qr-codes

Create a dynamic QR

Use dynamic QR codes when the destination may change after printing or when scans must be measured.

Request

{
  "name": "Packaging insert",
  "type": "dynamic",
  "destinationUrl": "https://example.com/post-purchase",
  "foregroundColor": "#111827",
  "backgroundColor": "#ffffff",
  "frameText": "Scan here"
}

Response

{
  "data": {
    "id": "qr_123",
    "name": "Packaging insert",
    "slug": "packaging-insert",
    "type": "dynamic",
    "status": "active",
    "destinationUrl": "https://example.com/post-purchase",
    "publicUrl": "https://usebrandcode.com/r/packaging-insert",
    "createdAt": "2026-05-19T12:00:00Z",
    "updatedAt": "2026-05-19T12:00:00Z"
  }
}

cURL

curl -X POST https://usebrandcode.com/api/v1/qr-codes \
  -H "Authorization: Bearer bc_test_xxx" \
  -H "Idempotency-Key: order_123_qr" \
  -H "Content-Type: application/json" \
  -d '{"name":"Packaging insert","type":"dynamic","destinationUrl":"https://example.com/post-purchase"}'

PATCH/api/v1/qr-codes/{id}/destination

Update destination after printing

Change the destination of a dynamic QR without replacing printed materials.

Request

{
  "destinationUrl": "https://example.com/spring-offer"
}

Response

{
  "data": {
    "id": "qr_123",
    "name": "Packaging insert",
    "slug": "packaging-insert",
    "type": "dynamic",
    "status": "active",
    "destinationUrl": "https://example.com/spring-offer",
    "publicUrl": "https://usebrandcode.com/r/packaging-insert",
    "createdAt": "2026-05-19T12:00:00Z",
    "updatedAt": "2026-05-19T13:20:00Z"
  }
}

cURL

curl -X PATCH https://usebrandcode.com/api/v1/qr-codes/qr_123/destination \
  -H "Authorization: Bearer bc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"destinationUrl":"https://example.com/spring-offer"}'

POST/api/v1/qr-codes/{id}/render

Render a transparent PNG

Render branded assets for print, packaging, PDFs, or digital placements.

Request

{
  "format": "png",
  "size": 2048,
  "transparent": true
}

Response

HTTP/1.1 200 OK
content-type: image/png
content-disposition: attachment; filename="pkg-2026.png"

<binary PNG body>

cURL

curl -X POST https://usebrandcode.com/api/v1/qr-codes/qr_123/render \
  -H "Authorization: Bearer bc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"format":"png","size":2048,"transparent":true}'

GET/api/v1/qr-codes/{id}/analytics

Read scan analytics

Read scans, devices, locations, referrers, quality, and business insights.

Request

GET /api/v1/qr-codes/qr_123/analytics?from=2026-05-01&to=2026-05-19

Response

{
  "data": {
    "qrCodeId": "qr_123",
    "totalScans": 12840,
    "uniqueVisitors": 9340,
    "lastScanAt": "2026-05-19T18:30:00Z",
    "breakdowns": {
      "devices": [{ "label": "mobile", "value": 10920 }],
      "operatingSystems": [{ "label": "iOS", "value": 6400 }],
      "browsers": [{ "label": "Safari", "value": 6120 }],
      "countries": [{ "label": "BR", "value": 8800 }],
      "regions": [{ "label": "SP", "value": 5320 }],
      "campaigns": [{ "label": "packaging_insert", "value": 12840 }],
      "sources": [{ "label": "qr", "value": 12840 }]
    }
  }
}

cURL

curl "https://usebrandcode.com/api/v1/qr-codes/qr_123/analytics?from=2026-05-01&to=2026-05-19" \
  -H "Authorization: Bearer bc_live_xxx"

POST/api/v1/destinations

Create a reusable destination

Create destinations once, then reuse them in dashboards, QR campaigns, or operational workflows.

Request

{
  "name": "Support WhatsApp",
  "type": "whatsapp",
  "targetUrl": "https://wa.me/15551234567"
}

Response

{
  "data": {
    "id": "dst_123",
    "name": "Support WhatsApp",
    "type": "whatsapp",
    "targetUrl": "https://wa.me/15551234567",
    "isActive": true,
    "createdAt": "2026-05-19T12:00:00Z",
    "updatedAt": "2026-05-19T12:00:00Z"
  }
}

cURL

curl -X POST https://usebrandcode.com/api/v1/destinations \
  -H "Authorization: Bearer bc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Support WhatsApp","type":"whatsapp","targetUrl":"https://wa.me/15551234567"}'

POST/api/v1/qr-codes/bulk

Create QR codes in bulk

Create up to 100 QR codes per request. The whole batch is checked against URL safety and plan limits.

Request

{
  "items": [
    {
      "name": "Table 01",
      "type": "dynamic",
      "destinationUrl": "https://example.com/menu?table=1",
      "tags": ["restaurant", "table"]
    },
    {
      "name": "Table 02",
      "type": "dynamic",
      "destinationUrl": "https://example.com/menu?table=2",
      "tags": ["restaurant", "table"]
    }
  ]
}

Response

{
  "data": [
    {
      "id": "qr_123",
      "name": "Table 01",
      "slug": "table-01-a1b2c3d4",
      "type": "dynamic",
      "status": "active",
      "destinationUrl": "https://example.com/menu?table=1",
      "publicUrl": "https://usebrandcode.com/r/table-01-a1b2c3d4",
      "createdAt": "2026-05-19T12:00:00Z"
    }
  ],
  "count": 2
}

cURL

curl -X POST https://usebrandcode.com/api/v1/qr-codes/bulk \
  -H "Authorization: Bearer bc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"name":"Table 01","destinationUrl":"https://example.com/menu?table=1"}]}'

POST/api/v1/landing-pages

Create a hosted landing page

Create a hosted post-scan page for campaigns that need copy, CTA buttons, and a public slug.

Request

{
  "title": "Spring launch",
  "subtitle": "Scan-only offer for store visitors.",
  "primaryButtonLabel": "Redeem offer",
  "primaryButtonUrl": "https://example.com/offer",
  "isPublished": true
}

Response

{
  "data": {
    "id": "lp_123",
    "title": "Spring launch",
    "slug": "spring-launch-x7k2p9",
    "isPublished": true,
    "primaryButtonUrl": "https://example.com/offer",
    "createdAt": "2026-05-19T12:00:00Z",
    "updatedAt": "2026-05-19T12:00:00Z"
  }
}

cURL

curl -X POST https://usebrandcode.com/api/v1/landing-pages \
  -H "Authorization: Bearer bc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"Spring launch","primaryButtonLabel":"Redeem offer","primaryButtonUrl":"https://example.com/offer"}'

POST/api/v1/webhooks

Register a signed webhook

Register a destination for signed BrandCode events. The secret is shown once; BrandCode stores an encrypted server-side copy and signs with the same raw secret you receive.

Request

{
  "name": "Production CRM webhook",
  "url": "https://example.com/webhooks/brandcode",
  "events": ["qr.created", "qr.scanned", "billing.updated"],
  "timeoutSeconds": 10,
  "maxAttempts": 5
}

Response

{
  "data": {
    "id": "wh_123",
    "name": "Production CRM webhook",
    "url": "https://example.com/webhooks/brandcode",
    "events": ["qr.created", "qr.scanned", "billing.updated"],
    "active": true,
    "secret": "bcwhsec_...",
    "secretShownOnce": true,
    "maxAttempts": 5,
    "timeoutSeconds": 10
  }
}

cURL

curl -X POST https://usebrandcode.com/api/v1/webhooks \
  -H "Authorization: Bearer bc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production CRM webhook","url":"https://example.com/webhooks/brandcode","events":["qr.scanned"]}'

JSONall endpoints

Error response shape

Errors use stable JSON codes so integrations can branch without parsing message strings.

Request

{
  "name": "Unsafe QR",
  "type": "dynamic",
  "destinationUrl": "javascript:alert(1)"
}

Response

{
  "error": {
    "code": "invalid_destination_url",
    "message": "destinationUrl invalida. Use uma URL http/https valida."
  }
}

cURL

curl -X POST https://usebrandcode.com/api/v1/qr-codes \
  -H "Authorization: Bearer bc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Unsafe QR","destinationUrl":"javascript:alert(1)"}'

Endpoint reference

GET/api/v1/api-keysList API keys from the signed-in dashboard session.workspace admin

POST/api/v1/api-keysCreate a test or live API key. The token is returned once.workspace admin

POST/api/v1/qr-codesCreate a static or dynamic QR code.qr:write

GET/api/v1/qr-codesList QR codes in the workspace.qr:read

GET/api/v1/qr-codes/{id}Read one QR code.qr:read

PATCH/api/v1/qr-codes/{id}Update QR metadata and status.qr:write

PATCH/api/v1/qr-codes/{id}/destinationChange the destination of a dynamic QR code.qr:write

DELETE/api/v1/qr-codes/{id}Archive or delete a QR code.qr:delete

POST/api/v1/qr-codes/{id}/renderRender PNG or SVG output, including transparent backgrounds.qr:read

GET/api/v1/qr-codes/{id}/analyticsRead scan analytics.analytics:read

POST/api/v1/qr-codes/bulkCreate QR codes in bulk.qr:write

POST/api/v1/qr-codes/bulk/destinationUpdate destinations in bulk.qr:write

POST/api/v1/qr-codes/bulk/statusPause, activate, or archive QR codes in bulk.qr:write

GET/api/v1/qr-codes/bulk/exportExport QR or analytics data in bulk.qr:read

GET/api/v1/destinationsList reusable destinations.destinations:read

POST/api/v1/destinationsCreate reusable destinations.destinations:write

GET/api/v1/landing-pagesList hosted landing pages.landing_pages:read

POST/api/v1/landing-pagesCreate hosted landing pages.landing_pages:write

POST/api/v1/campaignsCreate campaign folders.qr:write

GET/api/v1/webhooksList webhook endpoints.webhooks:read

POST/api/v1/webhooksRegister webhook endpoints.webhooks:write

Realtime analytics

For live integrations, subscribe to the signed qr.scanned webhook event. BrandCode queues each scan event, signs the delivery with HMAC, retries failed attempts, and keeps delivery logs in the developer dashboard. Use the analytics endpoint for aggregated dashboards, historical reporting, and reconciliation.

Live feedback

Use qr.scanned to update CRMs, Slack alerts, kiosks, lead routing, or customer-facing counters.

Signed delivery

Verify BrandCode-Signature before trusting event payloads in production systems.

Aggregate reports

Poll GET /api/v1/qr-codes/{id}/analytics for totals, breakdowns, trends, and exportable reporting.

{
  "type": "qr.scanned",
  "createdAt": "2026-05-25T18:30:00Z",
  "data": {
    "qrCodeId": "qr_123",
    "slug": "packaging-insert",
    "country": "BR",
    "city": "Sao Paulo",
    "device": "mobile",
    "browser": "Safari",
    "referrer": "qr",
    "utm": { "source": "qr", "campaign": "packaging" }
  }
}

Limits and billing

BrandCode does not charge API overage automatically. Each workspace has a monthly request limit based on its plan. Owners receive an email at 80% usage and another email if the limit is reached.

Warning

At 80% usage, the workspace owner gets an email with current usage and the recommended upgrade path.

Limit reached

When the monthly limit is reached, API calls return 429 until the next billing period or until a higher plan/add-on is configured.

Paid add-ons

Metered API add-ons should be sold explicitly through Stripe before enabling automatic overage billing.

Operational model

Use Idempotency-Key for creation and bulk workflows.

Use test mode keys for development and live keys only from Business+ workspaces.

QR redirects keep working even if analytics collection is delayed.

Webhooks use signed events for scans, destination changes, limits, abuse, and billing.

URL validation blocks unsafe protocols and supports domain controls for teams.

Responses use JSON errors with stable codes for invalid URL, missing scope, and rate limits.