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: decimal)
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: 95rewards_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: 0rewards_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 .
Step 6: Call the Recommend API Now test your setup by calling the Recommend API.
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 }, "scoreExplanation" : { "method" : "priority_weighted" , "priority" : 90 , "finalScore" : 0.89 } }, { "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", "channelId": "CHANNEL_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", "channelId": "CHANNEL_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", "channelId": "CHANNEL_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.
