QR Groups

A QR Group is a flat collection of QR codes that can share a destination and a status. Update the group once and every child code that inherits picks up the change on the next scan.

When to use a group

A printed batch (a thousand table cards, a poster run) where every code should route the same place.
A campaign you want to flip live, pause, or retire as a unit.
A staging area for codes you’ll later split into different destinations — start them grouped, then break out the ones that need their own routing.

Inheritance model

When a QR code is in a group and the group has a destination_type (or status) set, the child’s own field can be left blank to inherit the group’s. If the child sets its own, the child wins. This lets you bulk-configure a whole campaign of codes from the group level, and break individual codes out later when they need to diverge. Inheritance is resolved at scan time, not cached on the child. Update the group and the very next scan on any inheriting child picks up the change. The same resolution applies to status: child first, then group, then default.

Worked example

Group with a shared destination and an inactive child:

{
  "object": "qr_group",
  "id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "name": "Fall 2024 tabletop run",
  "status": "active",
  "destination": {
    "type": "page",
    "page": "a1c2e4f6-8b0d-4e2a-9c1b-3d5e7f9a2c4e",
    "chatbot": null,
    "knowledge_base": null,
    "url": null
  }
}

A child code that inherits:

{
  "object": "qr_code",
  "id": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "public_slug": "abc1234",
  "group_id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "status": "active",
  "destination": {
    "type": null,
    "page": null,
    "chatbot": null,
    "knowledge_base": null,
    "url": null
  }
}

destination.type is null on the child, so the scan resolves to the group’s page. A second child in the same group that overrides:

{
  "object": "qr_code",
  "id": "9e1d4f6a-3b2c-4f5d-8e7a-9c1b2d3e4f5a",
  "public_slug": "xyz9876",
  "group_id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "status": "active",
  "destination": {
    "type": "chatbot",
    "chatbot": "1b4c4f5d-9e8a-7c3b-2a1d-0f9e8f3a9d2e",
    "page": null,
    "knowledge_base": null,
    "url": null
  }
}

destination.type is set on the child, so the group is ignored — the scan goes to the chatbot.

To re-attach a broken-out child back to the group’s destination, PATCH the child with destination: { "type": null } (and any companion fields you want cleared). Inheritance resumes on the next scan.

CRUD workflow

Create the group

POST /qr-groups with a name and (optionally) a shared destination.

curl https://api.awardee.com/v1/qr-groups \
  -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fall 2024 tabletop run",
    "description": "1000 table cards, all Brunswick venues",
    "status": "active",
    "destination": {
      "type": "page",
      "page": "a1c2e4f6-8b0d-4e2a-9c1b-3d5e7f9a2c4e"
    }
  }'

await fetch("https://api.awardee.com/v1/qr-groups", {
  method: "POST",
  headers: {
    Authorization: "Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Fall 2024 tabletop run",
    description: "1000 table cards, all Brunswick venues",
    status: "active",
    destination: {
      type: "page",
      page: "a1c2e4f6-8b0d-4e2a-9c1b-3d5e7f9a2c4e",
    },
  }),
})

import requests

requests.post(
    "https://api.awardee.com/v1/qr-groups",
    headers={
        "Authorization": "Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e",
        "Content-Type": "application/json",
    },
    json={
        "name": "Fall 2024 tabletop run",
        "description": "1000 table cards, all Brunswick venues",
        "status": "active",
        "destination": {
            "type": "page",
            "page": "a1c2e4f6-8b0d-4e2a-9c1b-3d5e7f9a2c4e",
        },
    },
)

Mint child codes

Codes are minted in the dashboard and tied to the group via group_id. The v1 API is read/update-only for the QR code resource — new codes come from the dashboard.

Re-route the whole group

PATCH /qr-groups/{id} and update the destination object. Every inheriting child picks up the change on the next scan.

Pause or archive

Flip status on the group to inactive or archived to pause or retire every inheriting child at once.

Deleting a group

DELETE /qr-groups/{id} removes the group row. Child codes are not deleted — the database foreign key uses ON DELETE SET NULL, so children have their group_id cleared and stand alone. Their own destinations (if set) take over; inheriting children become unconfigured until you give them their own destination.

Deleting a group can silently break inheriting children if they relied on the group’s destination. Re-route or re-group orphans before deleting.

URL params and properties on groups

A group also carries its own static URL params and properties (separate tables: qr_group_url_params, qr_group_properties). At scan time they merge with the child’s params — child overrides on key collision.

group.url_params  = { utm_campaign: "fall24", utm_medium: "print" }
child.url_params  = { utm_medium: "table" }
merged on scan    = { utm_campaign: "fall24", utm_medium: "table" }
visitor scans with ?utm_source=email
final redirect    = ?utm_campaign=fall24&utm_medium=table&utm_source=email

Live visitor params win over the merged child-then-group baseline. Properties merge the same way: the group’s properties are inherited by every child, and a child’s own property wins on a key clash. The merged set is what the chatbot receives as scan context, and what a conversation’s qr_context reports.

Group properties

GET /qr-groups/{id}/properties lists the group’s properties; PUT /qr-groups/{id}/properties replaces the full set. Properties not in the request body are removed, and an empty properties array clears them all. Keys must be unique within a request (a duplicate returns 422). Both endpoints have the same request and response shape as QR code properties. PUT requires a plan that includes QR properties (402 otherwise).

curl -X PUT https://api.awardee.com/v1/qr-groups/b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e/properties \
  -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": [
      { "key": "Kettle Model Number", "value": "Breville LKE755" },
      { "key": "Floor", "value": "3" }
    ]
  }'

await fetch(
  "https://api.awardee.com/v1/qr-groups/b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e/properties",
  {
    method: "PUT",
    headers: {
      Authorization: "Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      properties: [
        { key: "Kettle Model Number", value: "Breville LKE755" },
        { key: "Floor", value: "3" },
      ],
    }),
  },
)

Group-level URL params remain managed in the dashboard for now. Per-child params and properties are available too — see QR Codes sub-resources.

Attach knowledge

Link the articles and folders that are specific to this group. Visitors who scan it get them on top of the chatbot’s own knowledge, so a question like “how do I turn the TV on?” is answered from this group’s manual, not a guess across every one. Group links apply to every code in the group; you can also send them on POST /qr-groups. Both arrays are replace-only: send the full desired set every time.

curl -X PATCH https://api.awardee.com/v1/qr-groups/1d0f9e8f-3a9d-2e1b-4c4f-5d9e8a7c3b2a \
  -H "Authorization: Bearer aw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "article_ids": ["5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9"],
    "category_ids": []
  }'

await fetch("https://api.awardee.com/v1/qr-groups/1d0f9e8f-3a9d-2e1b-4c4f-5d9e8a7c3b2a", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer aw_live_…",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    article_ids: ["5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9"],
    category_ids: [],
  }),
})

See Scan-specific knowledge for how scan links combine with the chatbot’s.

Webhook events

Event	Fires on
`qr_group.created`	`POST /qr-groups`
`qr_group.updated`	`PATCH /qr-groups/{id}`, `PUT /qr-groups/{id}/properties`, or any dashboard edit.
`qr_group.deleted`	`DELETE /qr-groups/{id}`. Children detach.

Subscribe and verify signatures per the webhooks guide.

Get started

Identity

Concepts

Webhooks

Chatbots

Customers

Articles

Article Categories

Article Tags

Knowledge Bases

Conversations

Conversation Tags

Submissions

Pages

QR Codes

Products

Objects

Custom Domains

Custom Domain Routes

Team

QR Groups

When to use a group

Inheritance model

Worked example

CRUD workflow

Deleting a group

URL params and properties on groups

Group properties

Attach knowledge

Webhook events

​When to use a group

​Inheritance model

​Worked example

​CRUD workflow

​Deleting a group

​URL params and properties on groups

​Group properties

​Attach knowledge

​Webhook events

When to use a group

Inheritance model

Worked example

CRUD workflow

Deleting a group

URL params and properties on groups

Group properties

Attach knowledge

Webhook events