Objects

A custom Object is an entity in your system — a vehicle, ticket, asset, client — paired with a permanent short scan URL of the form https://award.ee/o/{public_slug}. You decide what type means, what goes in metadata, and where scans route to.

{
  "id": "3a00bde3-f3b3-44a9-a16b-5d694e145440",
  "type": "vehicle",
  "external_id": "VIN-1HGCM82633A123456",
  "public_slug": "a1b2c3d",
  "url": "https://award.ee/o/a1b2c3d",
  "name": "2024 Toyota Hilux",
  "destination": {
    "type": "chatbot",
    "chatbot": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e"
  },
  "metadata": { "color": "blue", "owner": "fleet-3" },
  "is_active": true
}

When to reach for Objects

Objects are for any custom entity in your system that needs a permanent scan URL on top of it — typed by you, indexed by your external_id. The shape is intentionally generic so you can model whatever doesn’t fit a built-in resource. Typical examples:

Customer records / Clients — CRM contacts, accounts, leads.
Receipts / Invoices — issued documents, statements.
Vehicles, assets, equipment — fleet, tooling, serialised inventory.
Tickets, work orders — support cases, repair jobs, service tasks.
Anything custom — a row in your domain that needs a scan handle.

How Objects compare to the other entity types:

Anything else. You bring the type and external_id; we mint and own the slug. Built for integrations.

Products

Physical SKU-keyed catalog items, indexed by GTIN. For retail goods with barcodes. See Products.

QR Codes

Printed-first generic short URLs. Created in the dashboard and shipped on stickers. See QR Codes.

Idempotency by external_id

external_id is your identifier. Pass it on POST /objects and the call is idempotent on the pair (org_id, external_id). Replaying the same external_id never creates a duplicate row — it updates the existing one with whatever you sent and returns the same id and public_slug. The status code tells you what happened:

201 Created — new row inserted
200 OK — existing row was updated

curl -X POST https://api.awardee.com/v1/objects \
  -H "Authorization: Bearer aw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "vehicle",
    "externalId": "VIN-1HGCM82633A123456",
    "name": "2024 Toyota Hilux",
    "metadata": { "color": "blue", "fleet": 3 }
  }'

const res = await fetch("https://api.awardee.com/v1/objects", {
  method: "POST",
  headers: {
    Authorization: "Bearer aw_live_…",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "vehicle",
    externalId: "VIN-1HGCM82633A123456",
    name: "2024 Toyota Hilux",
    metadata: { color: "blue", fleet: 3 },
  }),
})
console.log(res.status) // 201 first call, 200 on replay
const object = await res.json()

import requests

res = requests.post(
    "https://api.awardee.com/v1/objects",
    headers={"Authorization": "Bearer aw_live_…"},
    json={
        "type": "vehicle",
        "externalId": "VIN-1HGCM82633A123456",
        "name": "2024 Toyota Hilux",
        "metadata": {"color": "blue", "fleet": 3},
    },
)
print(res.status_code)  # 201 first call, 200 on replay
object = res.json()

Objects without an external_id aren’t deduplicated — every POST creates a fresh row. Always pass an external_id from CRM/upstream syncs.

You can also look up by external_id without writing:

GET /objects?external_id=VIN-1HGCM82633A123456

Destinations

Every Object can route scans to one of four destinations. Set destinationType and the matching target ID/URL on create or update.

`destinationType`	Companion field	What happens on scan
`chatbot`	`destinationChatbot` (UUID)	Redirects to the chatbot’s public URL.
`page`	`destinationPage` (UUID)	Renders the page.
`knowledge_base`	`destinationKnowledgeBase` (UUID)	Lands on the KB index.
`url`	`destinationUrl` (string)	302 to an external URL.

When destinationType is null, the scan URL serves a default landing page.

curl -X PATCH https://api.awardee.com/v1/objects/3a00bde3-f3b3-44a9-a16b-5d694e145440 \
  -H "Authorization: Bearer aw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationType": "chatbot",
    "destinationChatbot": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e"
  }'

await fetch(
  "https://api.awardee.com/v1/objects/3a00bde3-f3b3-44a9-a16b-5d694e145440",
  {
    method: "PATCH",
    headers: {
      Authorization: "Bearer aw_live_…",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      destinationType: "chatbot",
      destinationChatbot: "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
    }),
  }
)

import requests

requests.patch(
    "https://api.awardee.com/v1/objects/3a00bde3-f3b3-44a9-a16b-5d694e145440",
    headers={"Authorization": "Bearer aw_live_…"},
    json={
        "destinationType": "chatbot",
        "destinationChatbot": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
    },
)

Properties

properties are typed key/value pairs attached to an Object. They power variable substitution inside chatbot prompts and pages ({{object.<type>.<key>}}) and show up in the dashboard as structured fields. Properties live at their own sub-resource:

GET /objects/{id}/properties
PUT /objects/{id}/properties — replace the full set

PUT is replace-only. Pass every property you want to keep; anything omitted gets removed. Keys are unique per object — you can’t ship the same key twice in a request.

curl -X PUT https://api.awardee.com/v1/objects/3a00bde3-f3b3-44a9-a16b-5d694e145440/properties \
  -H "Authorization: Bearer aw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": [
      { "key": "color",    "value": "blue" },
      { "key": "mileage",  "value": "42500" },
      { "key": "owner",    "value": "fleet-3" }
    ]
  }'

await fetch(
  "https://api.awardee.com/v1/objects/3a00bde3-f3b3-44a9-a16b-5d694e145440/properties",
  {
    method: "PUT",
    headers: {
      Authorization: "Bearer aw_live_…",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      properties: [
        { key: "color", value: "blue" },
        { key: "mileage", value: "42500" },
        { key: "owner", value: "fleet-3" },
      ],
    }),
  }
)

import requests

requests.put(
    "https://api.awardee.com/v1/objects/3a00bde3-f3b3-44a9-a16b-5d694e145440/properties",
    headers={"Authorization": "Bearer aw_live_…"},
    json={
        "properties": [
            {"key": "color", "value": "blue"},
            {"key": "mileage", "value": "42500"},
            {"key": "owner", "value": "fleet-3"},
        ]
    },
)

Properties can also be set inline on POST /objects by including a properties: [...] array on the create payload. The same replace semantics apply.

URL params

url_params are static query-string params merged into the scan-redirect URL. Use them to pass tracking, source attribution, or any static context downstream.

GET /objects/{id}/url-params
PUT /objects/{id}/url-params — replace the full set

Live params (whatever the visitor has on award.ee/o/<slug>?...) win on key collision.

curl -X PUT https://api.awardee.com/v1/objects/3a00bde3-f3b3-44a9-a16b-5d694e145440/url-params \
  -H "Authorization: Bearer aw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "url_params": [
      { "key": "utm_source",  "value": "qr" },
      { "key": "utm_medium",  "value": "sticker" }
    ]
  }'

The scan-redirect flow

Visitor scans

Visitor hits https://award.ee/o/{public_slug}. The slug is generated when the Object is created and never changes.

We resolve

We look up the Object, merge url_params (static) with the live query string (live wins), and emit an object.scanned webhook.

We redirect

Routed by destinationType: chatbot URL, page render, KB index, or external URL. If no destination is set, the default landing page is served.

Scans are never directly creatable through the API — they happen when someone actually loads the scan URL. To get notified, subscribe to the object.scanned webhook (see below).

Deletion

DELETE /objects/{id} removes the object. Future scans of its slug 404, and subsequent reads of the id return 404 not_found. Slugs are never reused — a deleted object’s public_slug will not be reassigned to a new object, even if you upsert a fresh row with the same external_id.

Attach knowledge

Link the articles and folders that are specific to this object. 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 object’s manual, not a guess across every one. You can also send them on POST /objects, including the external_id upsert. Both arrays are replace-only: send the full desired set every time.

curl -X PATCH https://api.awardee.com/v1/objects/3b2a1d0f-9e8f-3a9d-2e1b-4c4f5d9e8a7c \
  -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/objects/3b2a1d0f-9e8f-3a9d-2e1b-4c4f5d9e8a7c", {
  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

Four events fire over an Object’s lifecycle. Payloads ship inside the standard event envelope — see Webhooks overview.

event

New Object row inserted. Fires once per (org_id, external_id).

event

Any field on the row changed — including upsert replays that touched columns.

event

Someone loaded award.ee/o/{public_slug}. Use this to drive real-time notifications.

event

Object was deleted. Slug stays reserved and won’t be reassigned.

Sample object.created / object.updated payload (data field):

{
  "objectId": "3a00bde3-f3b3-44a9-a16b-5d694e145440",
  "orgId": "c1f5b2a7-9e8d-4f6a-b3c4-d5e6f7a8b9c0",
  "type": "vehicle",
  "externalId": "VIN-1HGCM82633A123456",
  "publicSlug": "a1b2c3d",
  "name": "2024 Toyota Hilux",
  "description": null,
  "metadata": { "color": "blue", "fleet": 3 },
  "destination": {
    "type": "chatbot",
    "chatbot": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
    "page": null,
    "knowledgeBase": null,
    "url": null
  },
  "isActive": true,
  "createdAt": "2026-05-23T10:00:00Z",
  "updatedAt": "2026-05-23T10:00:00Z"
}

Sample object.deleted payload:

{
  "objectId": "3a00bde3-f3b3-44a9-a16b-5d694e145440",
  "orgId": "c1f5b2a7-9e8d-4f6a-b3c4-d5e6f7a8b9c0",
  "type": "vehicle",
  "externalId": "VIN-1HGCM82633A123456",
  "publicSlug": "a1b2c3d",
  "deletedAt": "2026-05-23T11:00:00Z"
}

Object reference

Every field on the Object resource.

Chatbots

The most common scan destination.

Get started

Identity

Concepts

Webhooks

Chatbots

Customers

Articles

Article Categories

Article Tags

Knowledge Bases

Conversations

Conversation Tags

Submissions

Pages

QR Codes

QR Groups

Products

Objects

Custom Domains

Custom Domain Routes

Team

Objects

When to reach for Objects

Objects

Products

QR Codes

Idempotency by external_id

Destinations

Properties

URL params

The scan-redirect flow

Deletion

Attach knowledge

Webhook events

Next

Object reference

Chatbots

​When to reach for Objects

Objects

Products

QR Codes

​Idempotency by external_id

​Destinations

​Properties

​URL params

​The scan-redirect flow

​Deletion

​Attach knowledge

​Webhook events

​Next

Object reference

Chatbots

When to reach for Objects

Idempotency by external_id

Destinations

Properties

URL params

The scan-redirect flow

Deletion

Attach knowledge

Webhook events

Next