logo
Links•

Smart Rules reference: attributes, operators, and values

Every Smart Rules attribute, operator and accepted value — device names, country, region, continent and language codes, referrer and UTM formats — plus limits, validation messages, precedence and plan availability.

Avatar for undefined
CodeQR Team
Content Team

Use this page to look up what a Smart Rule can test, which values match, and the limits the app and the API enforce. For the decision logic and troubleshooting see How Smart Rules choose a destination; for payloads see Create Smart Rules with the API, MCP, and automations.

Availability

  • Plan — Business and above. Free, Starter and Pro: toggle shows a Business badge; API returns 403 forbidden for any non-empty rules
  • Links — all links; Smart Rules section in the link builder
  • QR codes — dynamic QR codes of type URL only; static QR codes and other types (Wi-Fi, vCard, WhatsApp, text, email, phone) do not evaluate rules
  • Surfaces — web app, REST API (rules on links and QR codes), MCP (create_link, update_link), automations through the API, webhooks (link.created, link.updated carry rules)

Anatomy of a rule

  • Condition — In the app: attribute + is / is not + value · In the API: attribute, operator, value · Required: all three, or none (= All traffic)
  • Destination — In the app: Destination URL · In the API: url · Required: one of url / split
  • Split — In the app: Split traffic (A/B test) → Variant URL + Variant weight (%) ×2–4 · In the API: split: [{ url, weight }] · Required: one of url / split

Attributes

  • Device — API attribute: device · What is compared: operating system name from the user agent · Accepted values: iOS, Android, Windows, Mac OS (shown as macOS), Linux · Example: iOS
  • Country — API attribute: country · What is compared: country of the visitor's IP address · Accepted values: ISO 3166-1 alpha-2, two letters (list in the app) · Example: BR, US, DE
  • Region (state) — API attribute: region · What is compared: subdivision of the visitor's IP address · Accepted values: ISO 3166-2 code without the country prefix · Example: SP, CA, NY
  • City — API attribute: city · What is compared: city of the visitor's IP address · Accepted values: city name as reported by geolocation · Example: São Paulo, New York
  • Continent — API attribute: continent · What is compared: continent of the visitor's IP address · Accepted values: AF Africa, AN Antarctica, AS Asia, EU Europe, NA North America, OC Oceania, SA South America · Example: SA
  • Language — API attribute: language · What is compared: first supported language in the browser's Accept-Language, region stripped · Accepted values: pt, en, es, fr, de, zh, ru, it, ja, ko (Português, English, Español, Français, Deutsch, 中文, Русский, Italiano, 日本語, 한국어) · Example: pt (matches pt-BR, pt-PT)
  • Referrer — API attribute: referrer · What is compared: hostname of the referring page, leading www. removed · Accepted values: bare domain · Example: instagram.com, l.facebook.com
  • UTM Source — API attribute: utm_source · What is compared: utm_source on the short link's query string · Accepted values: any text · Example: newsletter
  • UTM Medium — API attribute: utm_medium · What is compared: utm_medium on the short link's query string · Accepted values: any text · Example: email
  • UTM Campaign — API attribute: utm_campaign · What is compared: utm_campaign on the short link's query string · Accepted values: any text · Example: august-sale
  • UTM Term — API attribute: utm_term · What is compared: utm_term on the short link's query string · Accepted values: any text · Example: qr code
  • UTM Content — API attribute: utm_content · What is compared: utm_content on the short link's query string · Accepted values: any text · Example: poster-a

Notes:

  • The app offers dropdowns for Device, Country, Language and Continent; the other attributes are free text.
  • The API stores any string of 1–190 characters as value. A value the request never carries (mobile, desktop, tablet, Brazil, BR-SP, a full referrer URL) is saved and never matches.
  • Device is the operating system, so there is no "mobile" or "tablet". iPad with desktop Safari reports macOS.
  • Language is not location: it comes from the browser. Browsers that prefer a language outside the ten above match no Language rule.
  • UTM values are read from the short link as clicked (https://go.example.com/promo?utm_source=newsletter), not from the destination URL and not from the link's saved UTM fields. utm_id is not available.
  • When the request carries no value for the attribute (unknown location, no referrer, empty ?utm_source=, unsupported language), the rule does not match — with is or is not.

Operators

  • is — API operator: equals · Matches when: the request value equals the rule value, comparing the whole string, ignoring case
  • is not — API operator: not_equals · Matches when: the request has a value for the attribute and it differs from the rule value

There is no "contains", "starts with", regular expression or list of values. Each rule has exactly one condition; use several rules in order to combine them.

Split traffic

  • Variants — 2 to 4
  • Weight — whole number 1–100 per variant; weights add up to exactly 100
  • Distribute evenly — 2 → 50/50, 3 → 34/33/33, 4 → 25/25/25/25 (remainder to the first variant)
  • Assignment — hash of link + click ID → bucket 0–99 → variant by cumulative weight
  • Sticky for — 1 hour, or 30 days when Conversion tracking is on (cq_id cookie on the short link's path)
  • Where allowed — on any rule (with or without a condition); a rule with no condition (All traffic) always splits and must be last
  • Results — Analytics → URLs card, one row per destination URL

Limits

  • Rules per link or QR code — 20
  • Value length — 1–190 characters
  • Rules with no condition — at most one, in the last position
  • Destination URLs — must be valid URLs; every rule and variant URL is checked by the same safety scan as the main destination

Validation messages

App (inline, under the rule): Weights must add up to 100%. · Each weight must be a whole number between 1 and 100. · Every variant needs a URL. · A rule with no condition always splits traffic between the variants. (tooltip on the disabled split switch of an All traffic rule) · Smart rules are only available for dynamic QR codes (tooltip on the disabled toggle of a static QR code).

API (400, error.code unprocessable_entity, message prefixed with the rule index): A rule needs either a destination url or a traffic split, never both · A rule condition needs attribute, operator and value together · A rule without a condition must split traffic · Split weights must add up to 100 · A rule without a condition matches all traffic, so it must be the last one · Invalid URL · Invalid enum value. Expected 'device' | 'country' | … · String must contain at most 190 character(s) · Array must contain at most 20 element(s).

API (403 forbidden): Smart rules are available on the Business plan and above. Upgrade to Business to use this feature. · Smart rules can only be used on dynamic QR codes.

Precedence

  1. Password protection, expiration, banned links and the pre-redirect form are handled before any redirect rule.
  2. Link Cloaking wins over Smart Rules: a cloaked link shows its Destination URL; rules are ignored.
  3. Smart Rules, top to bottom, first match wins.
  4. iOS Targeting, Android Targeting, Geographic Targeting (older toggles), in that order.
  5. The link's Destination URL.

Incoming query parameters are appended to the chosen destination; with Conversion tracking on, cq_id is added. Redirects answer 302 (301 for a root domain).

Related articles