Examples

Objects shine when you sync a domain entity from an external system — a booking, a record, a job — and let the agent reach it via scan or follow-up.

Properties vs. metadata

Every example below uses both. The distinction matters:

properties (AI-visible)

Flat string key/values the chatbot can read when answering. These are your AI context. Stay readable — vin, next_service_due, customer_name. The agent references them as {{object.<type>.<key>}} in prompts and tool calls.

metadata (internal)

Free-form JSON for your integration — source-system IDs, raw payloads, audit fields. Stored, returned in API responses, but not surfaced to the agent.

Rule of thumb: if the chatbot needs to know it to do its job, it goes in properties. If it’s plumbing for your code, it goes in metadata. Set both in one call:

On create: pass properties: [...] and metadata: {...} to POST /v1/objects.
Updating: PUT /v1/objects/{id}/properties replaces the whole property set. PATCH /v1/objects/{id} updates metadata and other fields.

Industry patterns

Mechanics — Vehicle from a service-booking platform

A customer books service in Mitchell1, Tekmetric, or Shop-Ware. The integration creates a Vehicle Object so the agent can answer status questions, send reminders, and upsell maintenance based on mileage.

curl -X POST https://api.awardee.com/v1/objects \
  -H "Authorization: Bearer aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "vehicle",
    "external_id": "tekmetric:repair_order:48319",
    "name": "2019 Toyota Hilux — Sarah Chen",
    "properties": [
      { "key": "vin", "value": "JTEBU14R98K123456" },
      { "key": "make", "value": "Toyota" },
      { "key": "model", "value": "Hilux" },
      { "key": "year", "value": "2019" },
      { "key": "odometer_km", "value": "87420" },
      { "key": "last_service_date", "value": "2026-02-14" },
      { "key": "next_service_due_km", "value": "95000" },
      { "key": "customer_name", "value": "Sarah Chen" },
      { "key": "customer_phone", "value": "+61400000000" }
    ],
    "metadata": {
      "source": "tekmetric",
      "repair_order_id": 48319,
      "shop_id": "tek_44102"
    },
    "destination": {
      "type": "chatbot",
      "chatbot": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e"
    }
  }'

{
  "object": "object",
  "id": "5c1e2f3a-9d8b-4c7e-a6f5-1b2d3e4f5a6b",
  "type": "vehicle",
  "external_id": "tekmetric:repair_order:48319",
  "public_slug": "vh-7a2k",
  "url": "https://aw.rd/o/vh-7a2k",
  "name": "2019 Toyota Hilux — Sarah Chen",
  "destination": {
    "type": "chatbot",
    "chatbot": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e"
  },
  "is_active": true,
  "total_scans": 0,
  "created_at": "2026-05-24T03:12:00.000Z",
  "updated_at": "2026-05-24T03:12:00.000Z"
}

In the chatbot’s system prompt, reference fields with template syntax:

The customer's vehicle is a {{object.vehicle.year}} {{object.vehicle.make}}
{{object.vehicle.model}} (VIN {{object.vehicle.vin}}). They've driven
{{object.vehicle.odometer_km}} km and their next service is due at
{{object.vehicle.next_service_due_km}} km.

Vets — Pet from a clinic platform

A pet owner books with Vetter or RxWorks. A Pet Object holds breed, age, vaccination status, and owner contact so the agent can send vaccination reminders, post-visit care tips, and annual-checkup prompts.

curl -X POST https://api.awardee.com/v1/objects \
  -H "Authorization: Bearer aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "pet",
    "external_id": "vetter:patient:p_18421",
    "name": "Biscuit — Border Collie",
    "properties": [
      { "key": "species", "value": "dog" },
      { "key": "breed", "value": "Border Collie" },
      { "key": "name", "value": "Biscuit" },
      { "key": "dob", "value": "2021-08-04" },
      { "key": "weight_kg", "value": "18.4" },
      { "key": "c5_vaccination_due", "value": "2026-09-12" },
      { "key": "kennel_cough_vaccination_due", "value": "2026-09-12" },
      { "key": "desexed", "value": "true" },
      { "key": "owner_name", "value": "Marcus Patel" },
      { "key": "owner_phone", "value": "+61400111222" }
    ],
    "metadata": {
      "source": "vetter",
      "patient_id": "p_18421",
      "clinic_id": "v_771"
    },
    "destination": {
      "type": "chatbot",
      "chatbot": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e"
    }
  }'

{
  "object": "object",
  "id": "9b3c2d1e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
  "type": "pet",
  "external_id": "vetter:patient:p_18421",
  "public_slug": "pt-bsct",
  "url": "https://aw.rd/o/pt-bsct",
  "name": "Biscuit — Border Collie",
  "is_active": true,
  "created_at": "2026-05-24T03:12:00.000Z"
}

Attach the URL to the take-home pack. When the owner scans, the agent already knows Biscuit’s species, age, and which vaccinations are due.

Healthcare — Patient from a clinic platform

A patient books with Jane App, Cliniko, or HotDoc. A Patient Object carries appointment context and care flags so the agent can send pre-appointment reminders, follow-up care instructions, and rebooking prompts.

cURL

curl -X POST https://api.awardee.com/v1/objects \
  -H "Authorization: Bearer aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "patient",
    "external_id": "cliniko:patient:42188",
    "name": "Aisha Rahman",
    "properties": [
      { "key": "first_name", "value": "Aisha" },
      { "key": "appointment_kind", "value": "initial_consult" },
      { "key": "appointment_starts_at", "value": "2026-06-02T09:30:00+10:00" },
      { "key": "practitioner", "value": "Dr. Lin" },
      { "key": "allergy_flag", "value": "penicillin" },
      { "key": "condition_flag", "value": "asthma" },
      { "key": "insurance_provider", "value": "Medibank" }
    ],
    "metadata": {
      "source": "cliniko",
      "patient_id": 42188,
      "appointment_id": "ap_991821"
    },
    "destination": {
      "type": "chatbot",
      "chatbot": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e"
    }
  }'

Be deliberate about what goes in properties — anything in there is visible to the chatbot. For sensitive PHI, weigh whether the agent actually needs it to answer questions, or whether it’s better kept in your source system.

Restaurants — Reservation from a booking platform

A reservation lands in SevenRooms or OpenTable. A Reservation Object captures party size, dietary requirements, and occasion so the agent can confirm bookings, answer parking questions, and follow up for reviews.

cURL

curl -X POST https://api.awardee.com/v1/objects \
  -H "Authorization: Bearer aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "reservation",
    "external_id": "sevenrooms:reservation:r_55821",
    "name": "Patel party of 4 — Sat 8pm",
    "properties": [
      { "key": "starts_at", "value": "2026-05-31T20:00:00+10:00" },
      { "key": "party_size", "value": "4" },
      { "key": "occasion", "value": "birthday" },
      { "key": "dietary_notes", "value": "1 vegetarian, no nuts" },
      { "key": "guest_name", "value": "Reema Patel" },
      { "key": "guest_phone", "value": "+61400222333" },
      { "key": "table_section", "value": "garden" }
    ],
    "metadata": {
      "source": "sevenrooms",
      "reservation_id": "r_55821",
      "venue_id": "v_aurelia"
    },
    "destination": {
      "type": "chatbot",
      "chatbot": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e"
    }
  }'

Drop the scan URL into the SMS reminder. Guests scan for menu questions, parking info, or to change the time — without holding the line.

Real estate — Property enquiry from a CRM

A buyer enquires via REA Group, Zillow, or Follow Up Boss. A Property Enquiry Object pairs the listing with the buyer’s preferences so the agent can nurture, answer property questions, and prompt inspection bookings.

cURL

curl -X POST https://api.awardee.com/v1/objects \
  -H "Authorization: Bearer aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "property_enquiry",
    "external_id": "followupboss:lead:l_44021",
    "name": "12 Park St — Tom Walker",
    "properties": [
      { "key": "listing_address", "value": "12 Park Street, Newtown NSW" },
      { "key": "listing_bedrooms", "value": "3" },
      { "key": "listing_bathrooms", "value": "2" },
      { "key": "asking_price_aud", "value": "1480000" },
      { "key": "buyer_name", "value": "Tom Walker" },
      { "key": "buyer_phone", "value": "+61400333444" },
      { "key": "buyer_budget_aud", "value": "1500000" },
      { "key": "buyer_preferences", "value": "close to school, garage, north-facing" },
      { "key": "stage", "value": "qualified" },
      { "key": "next_open_home", "value": "2026-06-01T11:00:00+10:00" }
    ],
    "metadata": {
      "source": "followupboss",
      "lead_id": "l_44021",
      "listing_mls": "REA-2914488"
    },
    "destination": {
      "type": "page",
      "page": "9c4f8a1b-2d3e-4f5a-6b7c-8d9e0f1a2b3c"
    }
  }'

The buyer gets a personalised follow-up link. The agent answers spec questions, surfaces comparable listings from the linked KB, and offers an inspection slot — using the buyer’s stated budget and preferences as the lens.

Logistics — Shipment from a 3PL

A shipment is booked via Shippit, StarShipit, or a 3PL system. A Shipment Object tracks the delivery so the agent can proactively update on delays, answer ETA questions, and handle failed-delivery rebooking.

cURL

curl -X POST https://api.awardee.com/v1/objects \
  -H "Authorization: Bearer aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "shipment",
    "external_id": "shippit:tracking:SP-883712",
    "name": "Order #20451 → Brisbane",
    "properties": [
      { "key": "tracking_number", "value": "SP-883712" },
      { "key": "carrier", "value": "StarTrack" },
      { "key": "status", "value": "in_transit" },
      { "key": "eta", "value": "2026-05-27" },
      { "key": "recipient_name", "value": "Lila Singh" },
      { "key": "recipient_address", "value": "44 Boundary Rd, Brisbane QLD" },
      { "key": "contents_summary", "value": "1 × camera kit, 2 × accessories" },
      { "key": "order_total_aud", "value": "1289.00" }
    ],
    "metadata": {
      "source": "shippit",
      "order_id": "20451",
      "store": "shopify:lensvault"
    },
    "destination": {
      "type": "chatbot",
      "chatbot": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e"
    }
  }'

Add the URL to the dispatch SMS. When the courier ETA slips, push an updated status and eta via PUT /objects/{id}/properties — the agent surfaces the change before the customer has to ask.

More patterns

The same shape covers many other industries — pick the entity that matters in the source system and mirror it as an Object.

Industry	Entity	External source
Car dealerships	Lead	DealerSocket, VinSolutions
Law firms	Matter	Clio, PracticePanther
Construction & trades	Job	Buildertrend, ServiceM8
eCommerce	Order	Shopify, WooCommerce
Gyms	Member	Mindbody, Glofox
Dentists	Patient	Dental4Windows, Dentrix
Hotels	Guest	Opera PMS, Mews
Education	Student	Teachable, Thinkific
Beauty & salons	Client	Fresha, Timely
Property management	Maintenance request	Buildium, PropertyMe
Finance & accounting	Client	Xero Practice Manager
Security & alarms	Site	Simpro, ServiceMax

Same recipe each time: pick a stable external_id from the source, pick a consistent type, put AI-relevant fields in properties as flat key/values, keep integration plumbing in metadata, and point destination at the chatbot or page the customer should land on.

Where to next

Object reference

Every field documented.

Idempotent upsert

Replay-safe writes by external_id.

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

Properties vs. metadata

properties (AI-visible)

metadata (internal)

Industry patterns

More patterns

Where to next

Object reference

Idempotent upsert

​Properties vs. metadata

properties (AI-visible)

metadata (internal)

​Industry patterns

​More patterns

​Where to next

Object reference

Idempotent upsert

Properties vs. metadata

Industry patterns

More patterns

Where to next