Developers
This section explains how to use the BaseQR API for automation and system-to-system workflows. It provides an overview of authentication, basic request patterns, and where to find endpoint details and troubleshooting guidance.
What this section covers
• API quickstart — How to authenticate with an API key, make your first request, and follow a minimal build flow from creating a code to updating its destination and UTMs.
• Endpoints — Reference for the primary resources (for example, campaigns, codes, destinations) and common operations (create, update, list, export). Exact fields and request/response models are detailed on the Endpoints page.
• Error codes & troubleshooting — How errors are returned, common failure causes (authentication, validation, rate limits if applicable), and steps to remediate.
Authentication and security
• API keys — Admins create and revoke keys in Settings → API Keys. Keys inherit organization-level access. Store keys in a secure secret manager; avoid client-side use.
• Requests — Include the API key in request headers as documented in the quickstart. Use HTTPS for all calls.
• Rotation — Rotate keys on a regular cadence and whenever roles change. Revoke exposed keys immediately and replace them before resuming jobs.
Typical build flow
• Create a campaign — Use the API to create or select a campaign (name and description). Follow your internal naming standard for consistency.
• Create codes — Create one or many QR codes in the campaign. Provide the initial destination URL; UTMs may be included at creation or added later.
• Update midstream — Change destinations or UTM parameters at any time without reprinting. Use small, verifiable batches and confirm changes with a quick scan test.
• Export assets — Retrieve SVG/PNG/JPG for downstream systems that assemble print or digital creatives.
• Report and reconcile — Use API exports or in-app reports for Total Scans; align with GA4 using your UTM convention.
Reliability and safety
• Idempotency — Design jobs so retries do not create duplicates (for example, supply a client reference ID when supported, or check-before-create patterns).
• Validation — Validate URLs, required fields, and UTM formatting before sending. Reject rows that fail basic checks during bulk operations.
• Monitoring — Log request/response metadata, handle non-2xx statuses explicitly, and alert on successive failures.
Best practices
• Keep UTMs consistent — Standardize utm_source, utm_medium, and utm_campaign so GA4 reports align with BaseQR scans.
• Batch with care — For large imports/updates, start with a small subset, verify, then scale up.
• Document context — Write goals, placements, audience/regions, and UTM plan in the campaign description for handoffs across teams.