Platform Walkthrough

Overview

This walkthrough takes you from an empty KaireonAI instance to a working decisioning setup. By the end, you will have categories, Offers, channels, Creatives, a Decision Flow, and will have called the Recommend and Respond APIs.

This guide assumes you have completed the Quickstart and have KaireonAI running locally or on the playground at https://playground.kaireonai.com.

Step 1: Create a Business Hierarchy

Start by organizing your offers into a logical hierarchy.

Create a category

Go to Studio > Business Hierarchy and click + New Category.

Field	Value
Name	Credit Cards
Description	Consumer credit card products
Icon	credit-card
Color	#6366f1

Add custom fields:

annual_fee (number, required)
rewards_multiplier (number, required)
personalized_rate (computed, formula: 19.99 - customer.loyalty_score * 0.05, output type: number)

Create a sub-category

With the “Credit Cards” category selected, click + Sub-Category.

Field	Value
Name	Premium Cards
Description	High-rewards premium card products

Step 2: Create Offers

Create offers that represent the products you want to recommend.

Create your first offer

Go to Studio > Offers and click + New Offer.

Field	Value
Name	Platinum Rewards Card
Short Description	Earn 3x points on all purchases
Category	Credit Cards
Sub-Category	Premium Cards
Priority	High
Status	Draft

Custom fields:

annual_fee: 95
rewards_multiplier: 3

Create a second offer

Create another offer for variety:

Field	Value
Name	Cash Back Card
Short Description	2% cash back on everything
Category	Credit Cards
Sub-Category	Premium Cards
Priority	Medium

Custom fields:

annual_fee: 0
rewards_multiplier: 2

Activate both offers

Set both offers’ status to Active so they are eligible for decisioning.

Step 3: Create a Channel

Define how recommendations will be delivered.

Create an email channel

Go to Studio > Channels and click + New Channel.

Field	Value
Name	Marketing Email
Type	email
Delivery Mode	API
Impression Tracking	Explicit

Add a placement:

Name: hero_offer
Description: “Primary offer slot in email header”

Step 4: Create Creatives

Create content variants that define how each offer looks on the channel.

Create a creative for the Platinum card

Go to Studio > Creatives and click + New Creative.

Field	Value
Name	Platinum Card - Email
Offer	Platinum Rewards Card
Channel	Marketing Email
Template Type	email_html

Content:

{
  "subject": "You're invited, {{first_name}} - Earn 3x Rewards",
  "headline": "Platinum Rewards Card",
  "body": "Start earning 3x points on every purchase with a personalized rate of {{offer_rate}}% APR.",
  "ctaText": "Apply Now",
  "ctaUrl": "https://example.com/apply/platinum"
}

Personalization:

first_name -> customer.first_name, fallback: “Valued Customer”
offer_rate -> computed.personalized_rate, fallback: “19.99”

Create a creative for the Cash Back card

Repeat for the Cash Back Card with appropriate content.

Step 5: Create a Decision Flow

Build the pipeline that selects and ranks offers.

Create a new flow

Go to Studio > Decision Flows and click + New Flow.

Field	Value
Name	Credit Card Recommendations
Description	Selects the best credit card for each customer

Add an Enrich stage

Add an Enrich stage to load customer data:

Schema: customer_profile
Key field: customer_id
Fields: first_name, loyalty_score, credit_score, income

Add a Compute stage

Add a Compute stage to evaluate the personalized_rate computed field for each candidate offer.

Add a Filter stage

Add a Filter stage with qualification mode set to Apply All.

Add a Score stage

Add a Score stage using the scorecard engine.

Add a Rank stage

Add a Rank stage to produce the final ordered list. Set max offers to 2.

Save and activate

Save the flow and set status to Active.

Now test your setup by calling the Recommend API.

Playground
Local

curl -X POST https://playground.kaireonai.com/api/v1/recommend \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: YOUR_TENANT_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Requested-With: XMLHttpRequest" \
  -d '{
    "customerId": "cust_12345",
    "limit": 2,
    "channel": "email"
  }'

curl -X POST http://localhost:3000/api/v1/recommend \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: YOUR_TENANT_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Requested-With: XMLHttpRequest" \
  -d '{
    "customerId": "cust_12345",
    "limit": 2,
    "channel": "email"
  }'

Find your Tenant ID and API Key in Settings > API Explorer. Both are auto-populated. Click Manage Keys to view or create additional keys.

Expected response:

{
  "recommendationId": "rec_abc123",
  "customerId": "cust_12345",
  "decisionFlowKey": "df_credit_cards",
  "decisionFlowVersion": 1,
  "count": 2,
  "decisions": [
    {
      "offerId": "...",
      "offerName": "Platinum Rewards Card",
      "rank": 1,
      "score": 0.89,
      "channelName": "Email",
      "creativeId": "...",
      "categoryName": "Credit Cards",
      "personalization": {
        "personalized_rate": 17.49
      }
    },
    {
      "offerId": "...",
      "offerName": "Cash Back Card",
      "rank": 2,
      "score": 0.74,
      "channelName": "Email",
      "creativeId": "...",
      "categoryName": "Credit Cards",
      "personalization": {
        "personalized_rate": 18.24
      }
    }
  ],
  "meta": {
    "totalCandidates": 8,
    "afterQualification": 6,
    "afterSuppression": 6,
    "afterContactPolicy": 4,
    "degradedScoring": false
  }
}

Step 7: Record Outcomes with the Respond API

After the customer interacts with a recommendation, record the outcome.

Record an impression
Record a click
Record a conversion

curl -X POST http://localhost:3000/api/v1/respond \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: your-tenant-id" \
  -H "X-API-Key: your-api-key" \
  -H "X-Requested-With: XMLHttpRequest" \
  -d '{
    "customerId": "cust_12345",
    "creativeId": "CREATIVE_ID_FROM_RECOMMEND",
    "outcome": "impression",
    "idempotencyKey": "imp-001"
  }'

curl -X POST http://localhost:3000/api/v1/respond \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: your-tenant-id" \
  -H "X-API-Key: your-api-key" \
  -H "X-Requested-With: XMLHttpRequest" \
  -d '{
    "customerId": "cust_12345",
    "creativeId": "CREATIVE_ID_FROM_RECOMMEND",
    "outcome": "click",
    "idempotencyKey": "click-001"
  }'

curl -X POST http://localhost:3000/api/v1/respond \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: your-tenant-id" \
  -H "X-API-Key: your-api-key" \
  -H "X-Requested-With: XMLHttpRequest" \
  -d '{
    "customerId": "cust_12345",
    "creativeId": "CREATIVE_ID_FROM_RECOMMEND",
    "outcome": "convert",
    "conversionValue": 15000,
    "idempotencyKey": "conv-001"
  }'

Response (201 Created):

{
  "interactionId": "int_xyz789",
  "customerId": "cust_12345",
  "outcome": "impression",
  "classification": "neutral",
  "offerName": "Platinum Rewards Card",
  "creativeName": "Platinum — Email",
  "channelName": "Email",
  "categoryName": "Credit Cards",
  "status": "recorded",
  "timestamp": "2026-03-10T15:45:00Z"
}

The classification field maps the outcome to its business meaning: neutral (impression), positive (click, convert, accept), or negative (dismiss).

What’s Next?

Computed Values

Learn how to define formula-based fields for per-customer personalization.

API Tutorial

Deep dive into the Recommend and Respond APIs with advanced features.

Composable Pipeline

Build advanced Decision Flows with the v2 node-based pipeline.

Contact Policies

Set up frequency caps and suppression rules.

Behavioral Metrics

Create computed metrics from interaction history.

MCP Quickstart

Connect your AI IDE to KaireonAI for natural-language configuration.

Get Started

Tutorials

Use Cases

Decisioning

Studio

Data Pipelines

AI & ML

Operations & Reporting

Governance & Security

Integrations

Reference

Platform Walkthrough

Overview

Step 1: Create a Business Hierarchy

Step 2: Create Offers

Step 3: Create a Channel

Step 4: Create Creatives

Step 5: Create a Decision Flow

Step 7: Record Outcomes with the Respond API

What’s Next?

Computed Values

API Tutorial

Composable Pipeline

Contact Policies

Behavioral Metrics

MCP Quickstart

​Overview

​Step 1: Create a Business Hierarchy

​Step 2: Create Offers

​Step 3: Create a Channel

​Step 4: Create Creatives

​Step 5: Create a Decision Flow

​Step 6: Call the Recommend API

​Step 7: Record Outcomes with the Respond API

​What’s Next?

Computed Values

API Tutorial

Composable Pipeline

Contact Policies

Behavioral Metrics

MCP Quickstart

Overview

Step 1: Create a Business Hierarchy

Step 2: Create Offers

Step 3: Create a Channel

Step 4: Create Creatives

Step 5: Create a Decision Flow

Step 6: Call the Recommend API

Step 7: Record Outcomes with the Respond API

What’s Next?