API Quickstart

This page provides a minimal, end-to-end walkthrough for using the BaseQR API: authenticate, create a campaign, create a dynamic QR code, export assets, and update destinations/UTMs midstream. Refer to Endpoints for request/response details.

Prerequisites

• API key — An Admin creates an API key in Settings → API Keys, then shares it securely with your server-side environment.

• Server environment — Make requests from a backend (HTTPS). Avoid client-side usage.

1) Authenticate

• Header — Include your API key in the Authorization header on every request (see Endpoints for the exact header format).

• Transport — Use HTTPS only.

2) Create a campaign

• Action — Call the Create Campaign endpoint with a name and description.

• Recommendation — Mirror your internal naming standard (for example, 2025_q2_eventseries) and include goals, placements, audience/regions, and your UTM convention in the description for team alignment.

3) Create a dynamic QR code

• Action — Call the Create Code endpoint within the campaign. Provide:
  • destination URL (HTTPS)
  • optional UTM parameters (source, medium, campaign; optional content/term)
    
• Result — A single dynamic QR code is created (no type selection). It is Active by default and ready for export and testing.
  
  

4) Export the QR asset

• Action — Call the Export Asset endpoint for the code.

• Formats — SVG (print, scalable), PNG or JPG (raster placements).

• Tip — Store the exported file used in production to keep creative consistent across channels.

5) Update midstream (no reprint)

• Change destination — Call the Update Code endpoint to replace the destination URL.

• Revise UTMs — Add or correct UTM parameters to standardize attribution.

• Toggle availability — Set status to Active or Inactive to control scans during and after promotions.

• Note — These changes preserve the same printed/digital code and maintain continuity of reporting—one of BaseQR’s core advantages.

6) Bulk operations (optional)

• Create or update at scale — Use the Bulk Import endpoint with the CSV template to create many codes or update destinations/UTMs across existing codes in a single operation.

• Consistency — Apply the same UTM convention across rows so GA4 dashboards align with BaseQR scans.

7) Validate end-to-end

• Scan test — On iOS and Android (Wi-Fi and cellular), confirm routing and page load.

• UTM check — Ensure the final landing URL contains the intended parameters.

• GA4 Real-Time — Verify sessions appear under the expected source/medium/campaign.

Safety and operations

• Key handling — Keep keys in a secret manager, not in source control; rotate on a regular cadence and when personnel change.

• Idempotency — Design jobs so retries don’t create duplicates (for example, supply a client reference where supported, or check-before-create).

• Monitoring — Log non-2xx responses and alert on repeated failures; consult Error Codes & Troubleshooting for remediation steps.