A dynamic QR code API you run from your own code

Print a code once, then decide where it goes from your software. Change the destination, add rules, read every scan and hear about each one as it happens.

  • Change any code in one request
  • Your ids on every scan
  • Signed webhooks
curl -X PATCH https://pikaqr.com/api/v1/qr/$CODE_ID \
  -H "Authorization: Bearer $PIKAQR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "destination_url": "https://example.com/summer" }'

How a dynamic code works

A static code holds its address in the pattern, so it can never change. A dynamic code holds a short link such as https://pikaqr.com/r/q7Xk2LmP. When someone scans it, PikaQR looks up where that link should go right now, records the scan and sends them there.

Because the printed part never changes, you can change everything behind it from your own code: the destination, the rules, even whether it works at all.

Change the destination

Send only what changes with PATCH /qr/:id.

A new destination_url takes effect straight away for every printed copy. The reply gives the new version number, and the old address stays in the code’s history, which you can see in the dashboard.

GET /qr/:id returns the code with its current_destination, so your software can check where a code points before changing it. Set is_active to false to pause a code: scans show a not-found page until you turn it back on.

Text, phone, SMS, email, contact card, Wi-Fi and event codes are dynamic too. Change them by sending new content instead of a destination_url. Contact cards, Wi-Fi networks and events take their content as a JSON object.

Route scans with rules

Rules are part of Premium and work on website and menu codes.

Send the whole list to PUT /qr/:id/rules. Rules are checked from the top, the first match wins, and if none match, the scan goes to the main destination. Include a rule’s id when you send the list again to keep its history.

  • time: days of the week and a window in your time zone, which can run past midnight
  • date: a from and to date, for an event or a sale
  • device and platform: mobile, tablet or desktop, and iOS, Android or other
  • geo and language: the country of the scan and the language of the phone
  • param: a query parameter on the scanned link
  • split: a percentage for an A/B test, with each visitor kept on the same side
curl -X PUT https://pikaqr.com/api/v1/qr/$CODE_ID/rules \
  -H "Authorization: Bearer $PIKAQR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "type": "time",
        "label": "Lunch",
        "conditions": {
          "start_time": "11:00",
          "end_time": "15:00",
          "days_of_week": [1, 2, 3, 4, 5],
          "time_zone": "America/Chicago"
        },
        "destination_url": "https://example.com/lunch"
      },
      {
        "type": "language",
        "conditions": { "languages": ["es"] },
        "destination_url": "https://example.com/es/menu"
      }
    ]
  }'

Pass details through the link

If the scanned link has a query string, such as https://pikaqr.com/r/q7Xk2LmP?src=poster, PikaQR passes it on to the destination. Turn that off for a code with forward_params set to false.

To put a value in an exact place, write it as a placeholder in the destination’s path or query, such as https://example.com/offer?from={src}. The host and the values you set yourself never change, so nobody can point your code somewhere else.

Read scans and totals

GET /qr/:id/scans lists scans newest first, up to 200 at a time with limit and offset. Each one has the time, whether it was a first scan, the device, operating system, browser, language, country, the rule that matched and where the person went.

GET /qr/:id/analytics gives totals for a period, set with days: total and unique scans, and counts by day, device, country, language, rule and table. Free covers the last 7 days. Premium goes back up to 365 days per request.

import os
import requests

code_id = os.environ["CODE_ID"]
res = requests.get(
    f"https://pikaqr.com/api/v1/qr/{code_id}/analytics",
    headers={"Authorization": f"Bearer {os.environ['PIKAQR_KEY']}"},
    params={"days": 7},
)
totals = res.json()

print(totals["total_scans"], "scans,", totals["unique_scans"], "unique")
for day in totals["by_day"]:
    print(day["date"], day["count"])

Get a webhook for every scan

On Premium, each scan arrives at your server as a signed event.

Add an endpoint with POST /webhooks. Leave out qr_code_id to hear about every code, or set it to hear about one. The signing secret is in the reply, once. Use POST /webhooks/:id/test to send a ping, and GET /webhooks/:id/deliveries to see recent attempts and their results.

Events can arrive more than once if a delivery is retried, so use the event’s id to ignore repeats.

curl https://pikaqr.com/api/v1/webhooks \
  -H "Authorization: Bearer $PIKAQR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/pikaqr",
    "description": "Order system"
  }'

Keep your own ids with each code

Give a code up to 4 KB of metadata, such as an order id or a room number, and it comes back on every scan event. You don’t need a lookup table on your side.

Tags group codes: up to 20 per code. List them with GET /qr?tag=flyers, or search by title with q.

Questions

What is a dynamic QR code API?

An API for QR codes that hold a short link instead of a fixed address. Your software creates the codes, and can change where they go, add rules and read scans after they’re printed.

Does changing the destination change the printed code?

No. The printed code holds the same short link for good. Only where that link sends people changes, so every copy already printed follows the new destination.

How quickly does a change take effect?

Straight away. The next scan after a successful PATCH goes to the new destination.

Which kinds of codes can I change through the API?

Website, menu, text, phone, SMS, email, contact card, Wi-Fi and event codes. Website and menu codes take a destination_url. The others take content: a string, or a JSON object for contact cards, Wi-Fi and events. Rules work on website and menu codes.

Can I track scans without webhooks?

Yes. Every plan can read scans and totals from the API. Free covers the last 7 days. Webhooks, which push each scan to you, are part of Premium.

Dynamic QR code API: change codes after printing · PikaQR