Endpoints

This page outlines the primary API resources and common operations for creating campaigns, managing dynamic QR codes, exporting assets, and retrieving analytics. Use this as a structural guide; field names and response models are detailed in the reference linked from each endpoint in your developer portal.

Conventions

• Base URL — /v1/… over HTTPS.

• Auth — API key in request headers (see API quickstart).

• Format — JSON request/response unless noted. Asset exports return files.

• Pagination — page and page_size (or cursor) where applicable.

• Timestamps — ISO 8601 (UTC).

• Idempotency — Supply a stable client_reference on create operations when available to avoid duplicates.

Campaigns

• Create a campaign — POST /v1/campaigns
Fields: name (required), description (recommended: goals, placements, audience/regions, UTM plan).
Returns: campaign object.

• List campaigns — GET /v1/campaigns?query=&page=&page_size=
Filters: simple text search on name/description.

• Get a campaign — GET /v1/campaigns/{campaign_id}

• Update a campaign — PATCH /v1/campaigns/{campaign_id}
Fields: name, description.

• Delete a campaign (Admin) — DELETE /v1/campaigns/{campaign_id}

Campaign object (summary)

id, name, description, created_at, updated_at

Codes (QR)

• Create a code — POST /v1/campaigns/{campaign_id}/codes
Fields: destination_url (HTTPS), optional utm_source, utm_medium, utm_campaign, utm_content, utm_term, optional name, optional client_reference.
Returns: code object (status defaults to Active).

• List codes in a campaign — GET /v1/campaigns/{campaign_id}/codes?page=&page_size=&query=

• Get a code — GET /v1/codes/{code_id}

• Update a code — PATCH /v1/codes/{code_id}
Fields: destination_url, UTM fields, name, status (Active or Inactive).

• Toggle status — POST /v1/codes/{code_id}/status
Body: { "status": "Active" | "Inactive" }

• Export a code asset — POST /v1/codes/{code_id}/export
Body: { "format": "svg" | "png" | "jpg" }
Returns: file download (SVG/PNG/JPG).

Code object (summary)

id, campaign_id, name, destination_url, UTM fields, status (Active/Inactive), created_at, updated_at

Bulk import and updates

• Bulk import (create/update many codes) — POST /v1/campaigns/{campaign_id}/codes:bulk_import
Content: CSV file using the Bulk Import Template (link below).
Behavior: creates new codes and/or updates existing ones (destination and UTM fields; status if supported).
Response: summary of processed rows with per-row success/errors.

Analytics and reports

• Scan summaries — GET /v1/reports/scans?start=&end=&campaign_id=
Returns: Total Scans by day (or chosen interval) with optional campaign filter.

• Device breakdown — GET /v1/reports/devices?start=&end=&campaign_id=

• Location breakdown — GET /v1/reports/locations?start=&end=&campaign_id=
Note: geographic granularity depends on available data.

• Time patterns — GET /v1/reports/time_patterns?start=&end=&campaign_id=
Hour-of-day / day-of-week aggregates.

• Export reports — POST /v1/reports:export
Body: { "start": "...", "end": "...", "campaign_id": "...", "types": ["total_scans" | "devices" | "locations" | "time_patterns"], "format": "csv" | "xlsx" | "pdf" }
Returns: file download.

Integrations

• List integrations — GET /v1/integrations

• Google Analytics settings (read) — GET /v1/integrations/google_analytics
Purpose: confirm configuration status for documentation and internal checks. (Tracking itself occurs on your site; UTMs are applied to destination URLs in BaseQR.)

• API keys (Admin) —

o Create: POST /v1/api_keys

o List: GET /v1/api_keys

o Revoke: DELETE /v1/api_keys/{key_id}

Errors (summary)

Errors return a standard JSON structure:
{ "error": { "code": "string", "message": "human-readable description", "details": { ... } } }
See the Error Codes & Troubleshooting page for common codes and remediation.

Best Practices

• Create, then verify — After creating codes, perform a quick scan test and check GA4 Real-Time to confirm UTMs and page load.

• Use stable naming — Mirror utm_campaign with your campaign name for easier reconciliation.

• Prefer vector for print — Use format: "svg" in export calls for print workflows.

• Bulk with care — Start imports with a small subset, verify results, then scale.