API Reference: Tags (SimplyTags)

Overview

Simply Action Tags are dynamic Actions reached through QR, ordinary URL NFC, or Action Links. Standalone Actions redirect to an HTTP(S) URL or render a safe hosted Link Page. Record links, Wizards, per-record bulk generation, Fresh Scan, and attribution require an eligible paid Simply360 or Simply app base contract. The Tags API lives under /v1/action-tags, is privileged tier, and requires TEAM_ADMIN_SIMPLY_TAGS. Standalone API-key access additionally requires the 500-Action band or higher; first-party Cognito use follows the product UI entitlement.

The public identity is an opaque Action Simply ID. QR, NFC, and Action Link projections of the same identity count once. Interactions are never billed and bot traffic cannot force a capacity upgrade.

Key Concepts

• Tag — A unique identifier printed as a QR code or written to an NFC chip. Each tag has a Simply ID (returned as id) and a configured action.
• Action type — standalone supports URL and LINK_PAGE. DATA_WIZARD and DATA_RECORD are powered types.
• Status — DRAFT, ACTIVE, INACTIVE, ARCHIVED, or ARCHIVED_BY_DOWNGRADE. Only active Actions resolve.
• Link Page — linkPageSettings contains plain text plus one to five HTTP(S) calls to action. The contract is strict and rejects active content and unsafe schemes.
• Linked record — dataRecordSimplyId is powered-only and associates the Action with a record.
• Interactions — human, bot, and link-preview traffic is classified separately. Referrer queries are stripped.
• Fresh-scan verification — powered/provisioned paths can require fresh evidence. A plain QR or NFC URL does not prove physical presence.

List Tags

GET /v1/action-tags returns up to 500 tags per page (default limit 100). Filters include status, actionType, dataRecordSimplyId, dataCollectionSimplyId, hasLinkedRecord, labelSimplyIds, search, destinationDomain, and created/last-scan date ranges; sort accepts column:direction clauses.

const tags = await s360.actionTags.list({ status: 'ACTIVE' });

for (const tag of tags.data) {
  console.log(`${tag.id}: ${JSON.stringify(tag.name)} [${tag.actionType}]`);
}

curl -s "https://api.simply360.app/v1/action-tags?status=ACTIVE" \
  -H "Authorization: Bearer $S360_API_KEY"

Get a Tag

const tag = await s360.actionTags.get('STAG-1234-ABCD');
console.log(tag.data);

curl -s "https://api.simply360.app/v1/action-tags/STAG-1234-ABCD" \
  -H "Authorization: Bearer $S360_API_KEY"

Create a Tag

Body fields include name (required), notes, status, actionType, actionUrl, linkPageSettings, and the powered-only Wizard/record/Fresh Scan fields. The server rejects powered fields for a standalone Team rather than ignoring them.

const created = await s360.actionTags.create({
  name: 'Conference links',
  actionType: 'LINK_PAGE',
  linkPageSettings: {
    title: 'Conference resources',
    theme: 'SYSTEM',
    callsToAction: [
      { label: 'Schedule', url: 'https://example.org/schedule' },
      { label: 'Feedback', url: 'https://example.org/feedback' },
    ],
  },
});

console.log(`New tag: ${created.data.id}`);

Update a Tag

PUT /v1/action-tags/{simplyActionTagSimplyId} updates only the properties present in the body. Set dataRecordSimplyId to null to unlink the record.

await s360.actionTags.update('STAG-1234-ABCD', {
  status: 'INACTIVE',
});

Delete a Tag

await s360.actionTags.delete('STAG-1234-ABCD');

Scan History

GET /v1/action-tags/{simplyActionTagSimplyId}/scans returns retained detail newest first (default limit 100, max 500). It includes the declared interactionSource (QR, NFC, LINK, or UNKNOWN) and approximate city/region/country, but never returns the raw IP address. Raw user-agent values are masked after seven days, keyed abuse hashes expire after 30 days, and detail expires after 30 days on Free or 24 months on paid plans. Daily/lifetime aggregates remain without retaining lifetime request identifiers.

const scans = await s360.actionTags.listScans('STAG-1234-ABCD');

for (const scan of scans.data) {
  console.log(`${scan.scannedAt} — ${scan.resolveStatus} -> ${scan.resolvedDestination ?? '(none)'}`);
}

curl -s "https://api.simply360.app/v1/action-tags/STAG-1234-ABCD/scans" \
  -H "Authorization: Bearer $S360_API_KEY"

Bulk Generation and Analytics

Endpoint	Description
POST /v1/action-tags/bulk-generate	Powered, first-party operation for generating one Action per record. It is intentionally excluded from the standalone public API-key allowlist.
GET /v1/action-tags/analytics	Team-wide analytics: QR/NFC/link source counts, interactions, geography, attributed hosted-site sessions/page views/clicks, Wizard activity, cart additions, confirmed purchases, resulting record updates, tracked submissions, daily time series, top pages/clicks, and recent attributed activity. Filter by date range, status, action type, labels, collection, or record.
GET /v1/action-tags/{simplyActionTagSimplyId}/analytics	The same analytics summary scoped to one Action.

Standalone Scale Operations

Endpoint	Contract
GET /v1/action-tags/capabilities	Server-authoritative band, managed capacity, retention, domain allowance, and feature gates. Cognito Team Admin only.
POST /v1/action-tags/imports/csv	500+ band. RFC 4180, at most 5 MB/5,000 rows. Dry-run first; apply is atomic and requires Idempotency-Key.
GET /v1/action-tags/exports/csv	500+ band. Formula-safe, import-compatible CSV.
GET /v1/action-tags/analytics/export.csv	Retention-aware detail plus non-overlapping lifetime aggregates, including source counts and excluding raw IP addresses.
/v1/action-tags/domains	Paid plan. Create/list, explicitly verify DNS/certificate state, or remove a resolver alias by actionTagsDomainSimplyId.
/v1/action-tags/webhooks	500+ band. This is the exclusive management surface for HMAC-SHA256 Action Tags lifecycle subscriptions; the generic /v1/webhooks routes exclude them. The signing secret is returned once.

Product account, Team User, billing quote/payment, and saved-method endpoints are first-party Cognito Team Admin routes. They are not part of the public API-key surface. Bearer Action Credential issuance and presentation are also intentionally separate from standalone Action Tags operations.

Usage Notes

• Tag Simply IDs are encoded directly in the printed QR code or NFC chip and cannot be changed after printing.
• Scan location comes from IP geolocation, so city/region/country may be missing or approximate.
• Validate webhook signatures over the exact raw request body. Losing the one-time secret requires replacing the subscription.
• For CSV retry, reuse the same idempotency key only with the exact same body. A changed-body replay fails closed.
• Deactivate tags with status: "INACTIVE" instead of deleting: inactive tags preserve scan history but stop resolving (scans log resolveStatus: "DISABLED").
• For wizard-launching tags, the target wizard must belong to the same team; see API Reference: Data Wizards.
• QR rendering options (colors, logo, error correction) live in the qrCodeSettings object on each tag.