Scanely documentation

Build with Scanely.

Create and manage dynamic QR codes, automate destinations and read results through the REST API.

Updated November 6, 2026

Authentication & workspace scope

Base URL: https://scanely.io. API access is included in Business and Lifetime Business. Create a key in Dashboard → Settings → API Keys, then send it as a Bearer token. Store it on your server; never embed it in a public page. The complete key is only returned when created.

curl https://scanely.io/api/qr \
  -H "Authorization: Bearer sk_live_your_key_here"

Use Content-Type: application/json for JSON request bodies. For client workspace requests, also send X-Scanely-Workspace: workspace-id. A server integration without this header operates in the account’s personal workspace. Browser sessions can carry a selected-workspace cookie.

Keys inherit the account’s permissions, except that a key cannot delete the account or manage billing. Those actions stay in the signed-in dashboard. Within a client workspace, the member’s role controls access and the workspace owner’s plan supplies feature and usage limits. Viewer access does not permit writes. Account settings such as API keys and GA4 remain personal.

Create, read & update QR codes

POST /api/qr

Create a URL code

{
  "destinationUrl": "https://example.com/menu",
  "name": "Table 4",
  "campaignTag": "menu_q3"
}

Response:

{
  "id": "qr-id",
  "slug": "Ab3xY9k",
  "shortUrl": "https://scanely.io/r/Ab3xY9k"
}

Encode the returned shortUrl in the QR image to retain tracking and editable destinations. The API returns metadata, not image bytes. Download artwork from the dashboard or render the short URL with a QR library.

For URL codes, destinationUrl must be HTTP/HTTPS and at most 2,048 characters. Optional fields: name (255), campaignTag (100), fgColor, bgColor, gradientStart, gradientEnd, frameText, moduleStyle, eyeStyle, routingRules and redirectSchedule. Use six-digit hex colors. Keep frame text at 30 characters or fewer so it remains editable through PUT. Links that are new or changed in a request are also checked for safety; the answers are under Errors & limits.

GET /api/qr?tag=menu_q3
GET /api/qr/:id

List or retrieve codes

The list is an array of records, newest first; tag is an optional exact campaign-tag filter. A single-code request returns one record plus health status. Responses use stored snake_case fields such as destination_url and campaign_tag. The list adds scan_count; the single-code response adds scanCount.

JSON-valued fields such as redirect_schedule, routing_rules, routing_data, vcard_data and page_data are serialized strings or null: parse them before use. Boolean flags such as is_active are 0/1. password_hash is masked as protected or null. Responses may include additional fields; do not send the entire record back as an update.

A code that Scanely has blocked carries blocked_at (a timestamp) and blocked_reason: unsafe_link when the link check blocked it, admin when Scanely did. Both are null on a code that is not blocked. A blocked code never redirects: a scan gets a disabled page with HTTP 403 and is not recorded. The list carries only a code’s own blocked_at and blocked_reason, never a block taken from its Page.

GET /api/qr/:id also returns blocked, which is null or { at, reason, url?, threats?, sourcePageId?, isVariant? }. For unsafe_link, url is the link Google lists and threats holds Google’s threat types, such as SOCIAL_ENGINEERING, MALWARE or UNWANTED_SOFTWARE. isVariant is true when that link is one of the code’s A/B variants: every variant is checked, also while A/B testing is off, and a variant can be deleted on any plan. sourcePageId is present on a placement of a blocked Page, which is blocked with its Page. A note written by an admin is never returned.

PUT /api/qr/:id

Update selected fields

{
  "destinationUrl": "https://example.com/new-menu",
  "name": "Table 4 - patio",
  "isActive": true,
  "expiresAt": "2026-12-31T23:59:59Z"
}

Returns { "success": true }. Omitted fields are unchanged. The underlying QR type is not changed by this endpoint.

Update fieldsBehavior
destinationUrl, vcard, page, routingUpdate the content appropriate to the saved QR type. Contact, page and app-routing objects replace their stored object; include all fields you want to keep. destinationUrl is ignored on page, file and contact-card codes.
name, campaignTag, isActiveRename, organize, pause or resume. Null clears name or tag.
expiresAt, maxScansExpiry timestamp with timezone; null clears it. Positive integer maximum scan count; null clears it. A per-code cap can stop redirects, unlike the account’s monthly tracking allowance.
expiredUrlAn http or https link that scans go to after expiresAt or maxScans, instead of the expired page; null clears it. Setting one requires a paid plan. Unavailable on Pages.
passwordAt least four characters; null clears it. Unavailable for hosted files and contact cards, and incompatible with maxScans.
notifyEmail, notifyThreshold, muteHealthAlertsScan-count email and threshold (0-10,000), and a boolean to mute/unmute health monitoring.
fgColor, bgColor, frameText, gradientStart, gradientEnd, moduleStyle, eyeStyleVisual settings. Frame text is at most 30 characters on update. Modules: square, rounded, dots, classy, extra-rounded. Eyes: square, rounded, circle, leaf.
utmSource, utmMedium, utmCampaign, utmContent, utmTermCampaign parameters appended at redirect time.
redirectSchedule, routingRules, abTestingEnabledAdvanced routing. See the sections below for shapes and compatibility. Not available on page codes.

POST /api/qr/:id/duplicate

Duplicate a code

{
  "count": 3,
  "name": "Table {n}"
}

Both fields are optional. count defaults to 1: up to 50 copies at once on paid plans, 10 of a hosted file, one at a time on Free. Without name, one copy is named after the original with (copy) and several are numbered; {n} in a name places the number. Each copy keeps the destination, design and settings, including A/B variants, and gets its own slug with no scans. All copies are created or none. The response is the first copy plus copies, an array of { id, slug, shortUrl, name }. A code with a logo needs a paid plan (Starter, Pro, Business or any Lifetime plan); a code with an A/B test, Smart Routing or a schedule needs Pro, Business or any Lifetime plan. A page is copied once per request, as a new draft. A blocked code cannot be duplicated.

POST /api/qr/:id/safety-check

Check a blocked code again

Takes no body and needs write access to the code. For a code that the link check blocked, it checks every link of the code and unblocks the code when all of them check as safe. Only the links that need it are looked up again: a link that checked as safe recently keeps that result, and a listing that was looked up less than ten minutes ago is trusted. The lookups count toward the owner’s daily link checks. The answer is one of these:

AnswerMeaning
{ "blocked": false }Nothing for this call to lift: the code is not blocked, another request already unblocked it, or the block is not one the owner can lift. An admin block is lifted only by Scanely, and a placement of a blocked Page is unblocked through its Page.
{ "blocked": true, "released": true }Every link checked as safe and the code works again.
{ "blocked": true, "released": false, "url": "https://example.com/page", "threats": ["SOCIAL_ENGINEERING"] }Google still lists this link, the first one it lists. "isVariant": true is added when it is one of the code’s A/B variants. Change the link, or ask Google to review it, then check again.
503 We cannot check the links of this code right now. Try again later.The code stays blocked and no link is listed, but some link could not be checked, for example because Google could not be reached or a daily limit is spent. data.url names the first link that could not be checked: change or remove it, or check again later.

DELETE /api/qr/:id

Delete permanently

Returns { "success": true }. Deletes the code and its associated data; the printed link will stop working. Use isActive: false for a reversible pause.

GET /api/qr/redirect-map

Download the redirect map

Returns a CSV file with every code in the current workspace: name, type, short link, where it opens, all links a scan can reach, status and creation date. Static codes are left out, because they have no redirect.

QR types & uploads

POST accepts type: url (default), vcard, appstore, file or page, plus the static types wifi, phone, sms, email, text and event. Each returns the same id/slug/shortUrl shape; a static code never uses its short URL.

Scanely Pages

Create with type: "page" plus a page object, or a template when you want a preset. If page is present it is validated and stored; otherwise Scanely uses template or blank. Templates: menu, menu-classic, menu-cafe, flyer, flyer-product, flyer-service, flyer-hiring, flyer-open-house, event, event-workshop, event-invitation, event-wedding, event-party, contact, contact-profile, contact-portfolio, contact-equipment, reviews, reviews-minimal, blank, blank-story, memorial, tag, tag-found, community. An unknown name becomes blank. Pages start as inactive drafts. After saving, call POST /api/qr/:id/publish to activate the page. A scan then opens it at the returned short URL. Drafts use a shared Pages and QR slot. A/B testing, Smart Routing and schedules are not available on page codes.

{
  "type": "page",
  "name": "Dinner menu",
  "template": "menu"
}

Or send the full page object:

{
  "type": "page",
  "name": "Dinner menu",
  "page": {
    "template": "menu",
    "accent": "#183D3D",
    "blocks": [
      {
        "id": "header-1",
        "type": "header",
        "title": "Dinner",
        "subtitle": "Today",
        "assetId": ""
      },
      {
        "id": "text-1",
        "type": "text",
        "markdown": "Hours: 5-10 PM."
      }
    ]
  }
}

Update with PUT { page }:

{
  "page": {
    "template": "menu",
    "accent": "#183D3D",
    "blocks": [
      {
        "id": "header-1",
        "type": "header",
        "title": "Dinner",
        "subtitle": "Today",
        "assetId": ""
      },
      {
        "id": "text-1",
        "type": "text",
        "markdown": "Hours: 5-10 PM."
      }
    ]
  }
}

Optional PUT field pageLeadNotify (boolean) emails the account owner when a new lead arrives; it defaults to on. Upload a page image or PDF with POST /api/qr/:id/page-asset (multipart file, kind=image or kind=file), then set the returned id on the matching block’s assetId. Page photos and PDFs are included on Lifetime. File-QR hosting remains subscription-only.

A header block can carry logo: { "assetId": "asset-id" } on a paid plan: Starter, Pro, Business or any Lifetime plan. Upload the logo with kind=image; it does not count toward the photo allowance. A menu block can carry currency, a code such as USD or EUR, and currencyPosition, before or after. The symbol is added to prices that are a bare number; other prices stay as typed. In design, menuNavStyle (pills, outline, underline), menuNavLayout (wrap, scroll, list) and menuNavPosition (sticky, static) set how a menu’s section tabs look.

Contact card

{
  "type": "vcard",
  "name": "Alex Morgan",
  "vcard": {
    "firstName": "Alex",
    "lastName": "Morgan",
    "org": "Example Co",
    "title": "Sales",
    "phone": "+12125550100",
    "email": "alex@example.com",
    "website": "https://example.com",
    "whatsapp": "+12125550100",
    "linkedin": "https://www.linkedin.com/in/alex-morgan"
  }
}

firstName is required; each contact field is limited to 200 characters. A scan opens a hosted page with a downloadable vCard. An address or note is not part of the dynamic contact-card API.

whatsapp takes a number in international format (+ and 7 to 15 digits) and is shown as a chat button on the contact page; when the card has no phone, the vCard uses it as the mobile number. linkedin takes a public profile or company link (linkedin.com/in/… or linkedin.com/company/…, not an lnkd.in short link), is shown as a button and written to the vCard as a social profile. Both are optional and returned normalized.

App download

{
  "type": "appstore",
  "name": "Our app",
  "routing": {
    "ios": "https://apps.apple.com/",
    "android": "https://play.google.com/store/apps",
    "fallback": "https://example.com/app"
  }
}

fallback is required. Omit a store link or use an empty string when unavailable. iOS and Android devices use their corresponding link, otherwise the fallback is used.

Hosted file

Create with { "type": "file", "name": "Product brochure" }, then upload to the returned ID. The code cannot serve a file until the upload succeeds.

curl -X POST https://scanely.io/api/qr/QR_ID/file \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -F "file=@brochure.pdf"

POST /api/qr/:id/file uploads or replaces the file and returns { success, fileName, fileSize }. PDF, PNG, JPEG, WebP and GIF are supported, up to 20 MB each. File hosting requires a monthly subscription; it is excluded from Lifetime. Owner storage caps: Starter 500 MB, Pro 2 GB, Business 10 GB.

Static codes

{
  "type": "wifi",
  "name": "WiFi sign",
  "static": {
    "ssid": "Cafe Guests",
    "password": "latte2026",
    "encryption": "WPA",
    "hidden": false
  }
}

A static code prints its content into the pattern (the same payload as the free tools), so it has no destination, no scans and no redirect: GET /api/qr leaves it out and its /r/ link answers 404. List static codes with GET /api/dashboard/static-codes, which returns { items, total }, newest first: 60 per page by default, limit up to 200 and offset for the next page. The static object per type: wifi { ssid, password, encryption: "WPA" | "WEP" | "nopass", hidden }; phone { number }; sms { number, message }; email { to, subject, body }; text { text } (up to 800 characters); event { title, start, end, location, description } with local times as YYYY-MM-DDTHH:mm. GET /api/qr/:id returns it as the JSON string static_data. PUT accepts static, name, campaignTag, isActive and the design fields; other fields are refused. A static code uses one of the plan's shared Pages & QR slots.

QR logo

POST /api/qr/:id/logo accepts a multipart file: PNG, JPEG or SVG up to 500 KB. Returns { success, logoUrl }. DELETE /api/qr/:id/logo removes it. QR logos require a paid plan: Starter, Pro, Business or any Lifetime plan.

Timezone-aware redirect schedules

Send redirectSchedule on POST or PUT. It is available only on URL codes with Pro, Business or any Lifetime plan. The main destination is used outside a scheduled window. Page codes cannot use schedules.

Daily windows

{
  "destinationUrl": "https://example.com/menu",
  "redirectSchedule": {
    "mode": "daily",
    "timezone": "America/New_York",
    "windows": [
      {
        "start": "08:00",
        "end": "12:00",
        "url": "https://example.com/breakfast"
      },
      {
        "start": "17:00",
        "end": "22:00",
        "url": "https://example.com/dinner"
      },
      {
        "start": "12:00",
        "end": "15:00",
        "url": "https://example.com/brunch",
        "days": [
          "sat",
          "sun"
        ]
      }
    ]
  }
}

Use an IANA timezone such as America/New_York, America/Chicago, America/Denver, America/Los_Angeles, America/Phoenix, America/Anchorage or Pacific/Honolulu. Times are 24-hour HH:mm, evaluated in that timezone rather than the scanner’s timezone.

Up to 12 windows. Windows must not overlap, and equal start/end is invalid. Overnight windows are supported, such as 22:00 to 02:00. The start is inclusive and end exclusive. Daylight saving follows local clock time; the repeated hour matches twice and a skipped hour does not occur. A window can name its days with days, for example ["sat", "sun"], from mon to sun; without it the window repeats every day. Windows on different days can share the same hours. An overnight window belongs to the day it starts.

One-time range

{
  "redirectSchedule": {
    "mode": "once",
    "timezone": "America/New_York",
    "start": "2026-12-01T13:00:00Z",
    "end": "2026-12-01T17:00:00Z",
    "url": "https://example.com/offer"
  }
}

One-time start and end are absolute ISO timestamps with an explicit offset or Z. The example is 8:00 AM-12:00 PM in New York on December 1. Supply a valid IANA timezone for display. The end must follow the start. A timezone-less local datetime is not accepted.

Clear or replace a schedule

{
  "redirectSchedule": null
}

A schedule cannot be combined with Smart Routing or enabled A/B testing. When switching, clear routingRules and set abTestingEnabled: false before or in the same PUT request.

Legacy scheduleUrl, scheduleStart and scheduleEnd remain supported for one date range. Use a complete valid range, or clear all three with null. Do not mix legacy fields with a non-null redirectSchedule. Saving a new-format schedule replaces the legacy range.

Smart Routing & A/B variants

Smart Routing

{
  "routingRules": [
    {
      "conditions": [
        {
          "field": "country",
          "op": "in",
          "values": [
            "US",
            "CA"
          ]
        },
        {
          "field": "device",
          "op": "in",
          "values": [
            "mobile"
          ]
        }
      ],
      "url": "https://example.com/north-america"
    }
  ]
}

Send routingRules on POST or PUT for a URL code. Rules are evaluated in order; the first rule whose conditions all match wins. Otherwise the main URL is used. Unknown scanner attributes do not match a condition. Smart Routing is not available on page codes.

Condition fields: country (two-letter codes), language (language codes such as en or pt, matched against the first language of the scanner's browser, without a region), device (mobile, tablet, desktop), or os (windows, macos, android, ios, linux, other). Operators: in or not_in. Limits: 15 rules, 8 conditions per rule, 40 values per condition and 8 KB of rule data. Clear rules with null or an empty array.

A/B variants

GET /api/qr/:id/variants lists variants. Create one with:

POST /api/qr/:id/variants

{
  "destinationUrl": "https://example.com/offer-a",
  "label": "Offer A",
  "weight": 50
}

Returns { "id": "variant-id" }. Use PUT /api/qr/:id/variants/:variantId to update destinationUrl, label, weight or isActive, and DELETE at the same path to remove a variant. A variant can be deleted on any plan, also while A/B testing is off.

Up to five variants; use integer weights between 1 and 100 with a total no greater than 100. Enable with PUT /api/qr/:id and { "abTestingEnabled": true }. Browser assignments are sticky for up to 30 days via a cookie. Plan for one routing strategy per code. Smart Routing and A/B require Pro, Business or any Lifetime plan; schedules must be removed first. A/B testing is not available on page codes.

Bulk creation

POST /api/qr/bulk

{
  "items": [
    {
      "destinationUrl": "https://example.com/table-1",
      "name": "Table 1",
      "campaignTag": "menu"
    },
    {
      "destinationUrl": "invalid-url",
      "name": "Table 2"
    }
  ]
}

Example response:

{
  "created": [
    {
      "row": 1,
      "id": "qr-id",
      "slug": "Ab3xY9k",
      "shortUrl": "https://scanely.io/r/Ab3xY9k",
      "name": "Table 1",
      "destinationUrl": "https://example.com/table-1",
      "campaignTag": "menu"
    }
  ],
  "skipped": [
    {
      "row": 2,
      "reason": "Invalid URL format"
    }
  ],
  "total": 2
}

Accepts 1-1,000 URL-code rows on paid plans, subject to the owner’s remaining QR allowance. Row numbers are one-based. Invalid rows are skipped and reported; successful rows stay created. Check created and skipped instead of assuming the whole batch succeeded. Retrying the entire batch creates additional codes for successful rows. A row whose link breaks the link rules or is flagged as unsafe is skipped with the message listed under Errors & limits.

Analytics, exports & sharing

  • GET /api/scans/:qrId?period=30d returns the range, plan and per-code analytics, including totalScans, timeSeries, geoBreakdown, deviceBreakdown and browserBreakdown.
  • GET /api/dashboard/analytics?period=30d returns workspace-level analytics.
  • GET /api/dashboard/analytics/:type?period=30d returns a breakdown for locations, browsers, os, referrers, devices, hours or campaigns.
  • GET /api/dashboard/insights returns insights calculated from the current workspace’s data.
  • GET /api/dashboard/export?period=30d&qrId=QR_ID downloads raw scan CSV. The QR filter is optional; the workspace header applies. There is no campaign-tag filter or campaign-tag column in this export.
  • GET /api/qr/:id/leads lists first-party Scan Page leads as JSON (items, total, limit). Newest first, up to 200 rows. Fields: id, created_at, name, email, phone, message. Add ?format=csv on a paid plan for a CSV download.
  • GET /api/dashboard/leads lists workspace leads with the same lead fields plus qr_id, qr_name and qr_slug.

Periods: 7d, 30d (default), 90d, this_month, last_month, all or custom. Custom ranges use from=YYYY-MM-DD&to=YYYY-MM-DD. Free accounts are restricted to the current calendar month. Raw scan CSV requires Pro, Business or any Lifetime plan. Lead CSV on GET /api/qr/:id/leads?format=csv requires any paid plan.

Recorded scan times and hourly charts use UTC. Stored timestamps may use SQLite’s YYYY-MM-DD HH:mm:ss representation; interpret those as UTC. Repeated scans from the same hashed IP and QR within one hour are deduplicated. Unique counts are estimates, and approximate location can be missing. On paid plans, monthly tracking keeps full analytics up to twice the allowance, then stops recording without stopping ordinary redirects.

Public read-only analytics

POST /api/qr/:id/share creates or rotates a public link and returns { shareToken, shareUrl }. Rotation immediately invalidates the old link. DELETE /api/qr/:id/share revokes access. Requires Pro, Business or any Lifetime plan. Anyone with the link can view it, without login. GET /api/shared/:token is the public data endpoint.

Test without adding campaign scans

POST /api/qr/:id/test creates a test session for an active code and returns { id, url, expiresAt }. Open or encode this temporary URL, then read GET /api/qr/:id/test?session=TEST_ID for completed_at, device, country and expires_at (or null for an unknown session).

Tests expire in 15 minutes. Creating another session invalidates any unfinished one for that code. Test activity is excluded from campaign analytics, the scan allowance, GA4 and conversions. Do not distribute or print the temporary URL; test the final exported QR separately.

Conversion tracking

Connect a QR visit to a confirmed booking event from your site, then compare conversion rates per code. The booking must succeed before your integration sends the event.

Available with Pro, Business or any Lifetime plan. A personal or client workspace has one project, one website origin and one goal.

GET /api/conversions/settings
PUT /api/conversions/settings

{
  "origin": "https://example.com",
  "goal": "booking",
  "enabled": true
}

PUT returns the project id. Origin must use HTTPS without a path, query or fragment; local development permits HTTP on localhost or 127.0.0.1. Goals: lead, booking, purchase. Keep the workspace header consistent between configuration and reporting.

Browser integration

<script src="https://scanely.io/scanely.js"></script>
<script>
  Scanely.init({ project: "PROJECT_ID", consent: false });

  // Call from your consent manager after the relevant consent choice.
  function onAnalyticsConsentGranted() {
    Scanely.consent(true);
  }

  // Call only after your application confirms the booking succeeded.
  async function onBookingConfirmed(opaqueBookingId) {
    await Scanely.track("booking", {
      eventId: "booking_" + opaqueBookingId
    });
  }
</script>

The script uses the public project ID, never your secret API key. Call the event only after your application confirms the actual action. The event name must match the configured goal. Use an opaque, stable event ID for each action and reuse it on retries: 8-100 characters, letters, digits, underscores or hyphens. Never put contact details in it.

For a purchase project:

Scanely.track("purchase", {
  eventId: "order_a1b2c3d4",
  valueMinor: 4900,
  currency: "USD"
});

valueMinor is an integer amount from 0 to 10,000,000,000; currency is a three-letter uppercase code. The SDK sends to the public POST /api/conversions/event?project=PROJECT_ID endpoint using the allowed origin and signed scan reference. Prefer the SDK over constructing events manually.

Attribution starts with an eligible URL redirect whose final origin matches the project. The SDK uses session storage and sends events only after consent. The reference is valid for up to 30 days, limited by the browser tab’s session; there is no cross-device attribution. The latest matching visit in the tab is used. Redirect-side attribution and regular scan logging are separate from browser SDK consent.

GET /api/conversions/stats returns results for visits from the last 30 days. Goal completion is counted once per attributed visit. Purchase values are website-reported, not payment-provider verification. Disabling the project stops new tracking but keeps past data.

Client workspaces

Business or Lifetime Business owners can create up to 30 spaces. Send X-Scanely-Workspace for scoped requests. Editors can manage QR codes and conversion settings; viewers have read access. Only owners manage branding, invitations and roles. Owner plan limits are shared across all owned spaces.

GET /api/workspaces

List accessible spaces; returns items, active and canCreate.

POST /api/workspaces

Create with { "name": "Acme" }; returns id and name.

GET /api/workspaces/team

Read members and pending invitations in the selected client workspace.

POST /api/workspaces/invites

Owner: { "email": "editor@example.com", "role": "editor" }. Returns id, url, expiresInDays. Role can also be viewer.

POST /api/workspaces/accept

Accept with { "token": "invite-token" }, authenticated as the invited email. Returns workspaceId.

PATCH /api/workspaces/team

Owner: { "userId": "member-id", "role": "viewer" }, editor or remove; alternatively { "inviteId": "invite-id" } revokes an invitation.

PUT /api/workspaces/branding

Owner: send all fields: name, brandName, brandColor and brandLogo. Example below.

GET /api/workspaces/report

Read branded report data for the last 30 days as JSON. The dashboard generates the downloadable PDF.

Branding payload

{
  "name": "Acme",
  "brandName": "Acme Studio",
  "brandColor": "#285B49",
  "brandLogo": null
}

Names are limited to 80 characters. brandLogo is null or a PNG/JPEG base64 data URL; use an image under 200 KB. Invitations expire after seven days and can be used once by the specified email. The returned URL must be shared manually; no invitation email is sent automatically. Up to 50 pending invites per workspace.

POST /api/workspaces/select with { "workspaceId": "workspace-id" } or null changes the browser session’s selected workspace. Server integrations should use the header instead. Client workspaces become read-only when the owner loses workspace plan access.

Account integrations & saved designs

  • GET /api/user/plan reads current plan and usage information.
  • GET /api/user/api-keys lists keys; POST /api/user/api-keys with { "name": "Server integration" } returns id, key, prefix and name. Up to five keys. DELETE /api/user/api-keys/:id revokes a key.
  • GET /api/user/ga4 reads GA4 connection status. PUT /api/user/ga4 accepts measurementId and apiSecret; an empty measurementId disconnects. A new measurement ID needs its own secret. The secret is write-only. Requires Pro, Business or any Lifetime plan.
  • GET /api/dashboard/design-templates lists saved designs in the current workspace; POST at the same path saves a name and visual fields (fgColor, bgColor, gradientStart, gradientEnd, frameText, moduleStyle, eyeStyle). DELETE /api/dashboard/design-templates/:id removes one. Up to 50 saved designs per workspace; names are limited to 60 characters.

GA4 scan events and Scanely conversion events are separate integrations. Print PDFs are generated in the browser, either from the public static tools or a saved QR’s dashboard Print kit. Analytics PDFs are generated in the dashboard. There is no public PDF-rendering endpoint.

Webhooks

Webhooks send each recorded scan and each new Page lead to your own HTTPS endpoint as JSON, as it happens. Add one in the dashboard under Settings > Webhooks, up to three per account. They are included in Pro, Business and every Lifetime plan, and cover the client workspaces of the account. They are set up in the browser, not through an API key, so a leaked key cannot redirect your leads.

For Zapier, use Webhooks by Zapier with a Catch Hook trigger. For Make, use a Custom webhook. Paste the address they give you, then press Send test: it sends a sample of each event you chose, marked "test": true, so that they can learn the fields.

Events

scan.created

{
  "id": "scan-id",
  "type": "scan.created",
  "created_at": "2026-11-05T12:00:00.000Z",
  "data": {
    "code": {
      "id": "qr-id",
      "slug": "Ab3xY9k",
      "name": "Table 4",
      "type": "url",
      "short_url": "https://scanely.io/r/Ab3xY9k",
      "workspace_id": null
    },
    "destination_url": "https://example.com/menu",
    "scan": {
      "country": "US",
      "city": "Chicago",
      "device": "mobile",
      "browser": "Safari",
      "os": "iOS"
    }
  }
}

lead.created. Here page is the Page and code is the printed placement that was scanned, which is the Page itself when it has no placements.

{
  "id": "lead-id",
  "type": "lead.created",
  "created_at": "2026-11-05T12:00:00.000Z",
  "data": {
    "page": {
      "id": "page-id",
      "slug": "Ab3xY9k",
      "name": "Open day",
      "workspace_id": null
    },
    "code": {
      "id": "placement-id",
      "slug": "Cd4zX1m",
      "short_url": "https://scanely.io/r/Cd4zX1m"
    },
    "lead": {
      "name": "Ann Lee",
      "email": "ann@example.com",
      "phone": "+1 555 0100",
      "message": "Please call me."
    }
  }
}

Only scans Scanely records are sent: a repeat scan by the same visitor within an hour, test scans and scans above twice the monthly allowance are not recorded, so they send nothing. destination_url is the address the scan was sent to, before UTM parameters, and null on Pages, contact cards and files.

Delivery

  • Each delivery is a POST with X-Scanely-Event, X-Scanely-Delivery (the event id) and X-Scanely-Signature.
  • Answer with a 2xx status within 10 seconds. Redirects are not followed and count as a failure, except the 302 Google Apps Script answers with after it has run. Scanely does not read the body of the answer.
  • Failed deliveries are tried again for about 3 days, sooner when the endpoint starts answering. Up to 500 scans and 2,000 leads wait per endpoint; a scan past that is not kept. An endpoint that still fails after 3 days is turned off and the owner gets one email.
  • A delivery can arrive more than once and out of order. Use id to ignore repeats.
  • A slow or failing endpoint never delays a scan or a form.

Checking the signature

The signing secret is shown once, when you add the endpoint. X-Scanely-Signature looks like t=1793880000,v1=..., where v1 is the HMAC-SHA256 hex digest of the timestamp, a dot and the raw body.

import { createHmac, timingSafeEqual } from 'node:crypto'

// rawBody is the request body exactly as received, before any JSON parsing.
function isFromScanely(rawBody, signatureHeader, secret) {
  const { t, v1 } = Object.fromEntries(signatureHeader.split(',').map(part => part.split('=')))
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300
  return fresh && v1?.length === expected.length && timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
}

Errors & limits

StatusMeaning
400Invalid input, unsupported combinations, invalid dates, file validation failure or a link that breaks the link rules. Read the response message.
401Missing or invalid authentication.
403Insufficient plan, role, capacity or storage, an invalid public conversion origin/reference, or an API key of a suspended account.
404Resource not found or inaccessible in the current scope.
409A conflict or capacity constraint, for example reaching the pending workspace invitation limit, a code changed by another request or duplicating a blocked code.
413Conversion event payload too large.
422A link in the request is flagged as unsafe by Google Safe Browsing.
500Server-side failure, such as an unavailable file storage service.
503A service the request needs is temporarily unavailable, for example the link check in POST /api/qr/:id/safety-check. Try again later.

Success and error shapes vary by endpoint; use the HTTP status and returned message. Write requests are not generally idempotent. Inspect the result before retrying creation, bulk imports or invitation requests. Conversion event IDs provide event deduplication.

See the plan capability matrix for QR, tracked-scan and storage allowances. Dates sent for expiry and one-time ranges should include their timezone offset; daily schedules use local clock times plus a named timezone.

Link safety, blocked codes & suspended accounts

Scanely checks the links a scan can lead to: a code’s destination, app-store links, Smart Routing and schedule links, a link after expiry, A/B variants, a contact card’s website and the links of a Page, which are checked when the Page is published. Scanely’s own short links and tel: and mailto: links are skipped. A save checks only the links it adds or changes, so a code with an older link keeps saving other edits. These answers are exact English text:

StatusAnswer
422This link is flagged as unsafe by Google Safe Browsing. Choose a different destination.
A save adds or changes a link that Google lists as phishing, malware or unwanted software: create, update, variants and publish.
400Use a web address with a domain name, not an IP address.
A new or changed link points to an IP address, however it is written.
400Use a public web address.
A new or changed link points to localhost, a .localhost name or a host without a dot.
400Link shorteners hide where a code leads. Use the full address of the page instead.
A new or changed link goes through a link shortener or another QR service’s redirect domain, such as bit.ly. Share links of platforms such as youtu.be, maps.app.goo.gl or wa.me stay allowed.
400Too many new links to check at once. Save fewer new links at a time.
One save adds more than 30 links that still need a check.
400We cannot check new links right now. Try again later.
A Free account’s save adds a link that could not be checked because the account’s daily link checks, or the day’s checks for all accounts, are used up. They reset at 00:00 UTC.
409This code changed in another window. Reload it and try again.
PUT /api/qr/:id or PUT /api/qr/:id/variants/:variantId: a link of the code changed after your request read it, or the variant was deleted, for example in another window. Read the code again and resend what you still want to change.
409This code is blocked. Fix its link before duplicating it.
POST /api/qr/:id/duplicate on a blocked code.
403This account is suspended. Contact hello@scanely.io.
Any request with an API key or WordPress connection of a suspended account. Signing in is refused with the same message, and scans of the account’s codes show the disabled page.

A link that cannot be checked right now, for example because Google did not answer in time, passes and is checked later. Live links are also checked again regularly. When Google lists one, Scanely blocks the code, emails its owner and shows scanners a disabled page. Read blocked_at and blocked_reason on the code, and call POST /api/qr/:id/safety-check once the link is fixed. In bulk creation, the unsafe-link message and the three link-rule messages appear as the reason of a skipped row.