Change where a printed code points

The whole point of a dynamic code: the poster stays on the wall while the destination behind it changes. Three calls.

1. Find the codeCopy Anchor Link

List codes filtered by name. q matches part of the name; the response carries the ids you need.

curl "https://api.kuikcode.com/v1/codes?q=front%20window" \
  -H "Authorization: Bearer kc_live_..."

{
  "data": [
    {
      "id": "K02bEPC2SmtopwPr6S-jt",
      "shortCode": "Ab3dE9xYz",
      "name": "Front window",
      "scanUrl": "https://kuikco.de/p/Ab3dE9xYz",
      "destination": { "type": "url", "url": "https://example.com/spring-menu", "pageId": null, "summary": "example.com/spring-menu" },
      "folderId": "f_9n2",
      "tags": ["signage"],
      "archived": false,
      "scans": 123
    }
  ],
  "next_cursor": null
}

Keep the id. shortCode and scanUrl are what is printed and never change.

2. Point it somewhere newCopy Anchor Link

PATCH /codes/{id} with a new destination. Everything else about the code, design, tags, tracking settings, is left as it is.

curl -X PATCH https://api.kuikcode.com/v1/codes/K02bEPC2SmtopwPr6S-jt \
  -H "Authorization: Bearer kc_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "destination": { "type": "url", "url": "https://example.com/summer-menu" } }'

To land on a KuikPage instead, send { "type": "page", "pageId": "..." } with an id from GET /pages.

The response is the updated code. Printed copies follow within a minute; the scan handler caches a code's destination for at most sixty seconds.

3. ConfirmCopy Anchor Link

curl https://api.kuikcode.com/v1/codes/K02bEPC2SmtopwPr6S-jt \
  -H "Authorization: Bearer kc_live_..."

destination.url reads the new address. Scans from then on appear under the new destination in GET /codes/{id}/scans and in the dashboard's Top destinations.

Many codes at onceCopy Anchor Link

When a campaign ends, repoint every code in it in one call with PATCH /codes/bulk, up to a hundred ids:

curl -X PATCH https://api.kuikcode.com/v1/codes/bulk \
  -H "Authorization: Bearer kc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["K02bEPC2SmtopwPr6S-jt", "Zq9vX1mN4kLp8rTb2cWd0"],
    "destination": { "type": "url", "url": "https://example.com/closed-for-season" }
  }'

The response lists updated and any failed ids with a reason. Ids from another workspace are ignored rather than reported.

Good to knowCopy Anchor Link

• A read-only key cannot do step 2; it answers 403 insufficient_scope.
• Codes made in the dashboard with other destination kinds (vCard, WiFi, Smart Rules...) come back with their engine name in destination.type. Switching them to url or page through the API works; editing the richer kinds stays in the dashboard.
• Archived codes are listed with ?archived=true. Set "archived": false in a PATCH to bring one back.

Smart rules through the APICopy Anchor Link

A destination can also be a set of rules. PATCH /codes/{id} (or POST /codes) with destination.type = "smartRules" takes a fallbackUrl and an ordered list of rules; the first rule whose conditions hold decides where the scan lands.

{
  "destination": {
    "type": "smartRules",
    "fallbackUrl": "https://example.com",
    "rules": [
      { "name": "iPhone", "url": "https://apps.apple.com/app/id123", "conditions": [{ "type": "os", "value": "ios" }] },
      { "name": "Android", "url": "https://play.google.com/store/apps/details?id=x", "conditions": [{ "type": "os", "value": "android" }] },
      { "name": "Spain, weekdays", "url": "https://example.es", "conditions": [{ "type": "country", "value": "ES" }, { "type": "day", "days": [1, 2, 3, 4, 5] }], "joins": ["and"] }
    ]
  }
}

Condition types: os (ios, android, windows, macos, linux, other), country (ISO 3166 alpha-2), language (ISO 639-1), time (before, after, between, HH:MM in the scanner's local time; a window past midnight wraps), date (before, after, on, YYYY-MM-DD), day (weekdays 0 to 6, Sunday first), totalScans and uniqueScans (gt, lt, eq), location (lat, lng, radiusMeters). Conditions in one rule chain left to right with joins. Smart rules are included from the PRO plan; GET /codes/{id} returns them under destination.rules, and sending a url destination later removes them.