Skip to main content
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

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.dev/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"
    }
  }'
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.
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.dev/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"
    }
  }'
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.
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.dev/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.
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.dev/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.
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.dev/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.
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.dev/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.
IndustryEntityExternal source
Car dealershipsLeadDealerSocket, VinSolutions
Law firmsMatterClio, PracticePanther
Construction & tradesJobBuildertrend, ServiceM8
eCommerceOrderShopify, WooCommerce
GymsMemberMindbody, Glofox
DentistsPatientDental4Windows, Dentrix
HotelsGuestOpera PMS, Mews
EducationStudentTeachable, Thinkific
Beauty & salonsClientFresha, Timely
Property managementMaintenance requestBuildium, PropertyMe
Finance & accountingClientXero Practice Manager
Security & alarmsSiteSimpro, 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.