> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform Walkthrough

> End-to-end guide — from creating your first category and offers to calling the Recommend API and recording outcomes.

## 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.

<Info>
  This guide assumes you have completed the [Quickstart](/quickstart) and have KaireonAI running locally or on the playground at `https://playground.kaireonai.com`.
</Info>

## Step 1: Create a Business Hierarchy

Start by organizing your offers into a logical hierarchy.

<Steps>
  <Step title="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)
  </Step>

  <Step title="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>
</Steps>

## Step 2: Create Offers

Create offers that represent the products you want to recommend.

<Steps>
  <Step title="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
  </Step>

  <Step title="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
  </Step>

  <Step title="Activate both offers">
    Set both offers' status to **Active** so they are eligible for decisioning.
  </Step>
</Steps>

## Step 3: Create a Channel

Define how recommendations will be delivered.

<Steps>
  <Step title="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>
</Steps>

## Step 4: Create Creatives

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

<Steps>
  <Step title="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:

    ```json theme={null}
    {
      "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"
  </Step>

  <Step title="Create a creative for the Cash Back card">
    Repeat for the Cash Back Card with appropriate content.
  </Step>
</Steps>

## Step 5: Create a Decision Flow

Build the pipeline that selects and ranks offers.

<Steps>
  <Step title="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 |
  </Step>

  <Step title="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
  </Step>

  <Step title="Add a Compute stage">
    Add a **Compute** stage to evaluate the `personalized_rate` computed field for each candidate offer.
  </Step>

  <Step title="Add a Filter stage">
    Add a **Filter** stage with qualification mode set to **Apply All**.
  </Step>

  <Step title="Add a Score stage">
    Add a **Score** stage using the scorecard engine.
  </Step>

  <Step title="Add a Rank stage">
    Add a **Rank** stage to produce the final ordered list. Set max offers to 2.
  </Step>

  <Step title="Save and activate">
    Save the flow and set status to **Active**.
  </Step>
</Steps>

## Step 6: Call the Recommend API

Now test your setup by calling the Recommend API.

<Tabs>
  <Tab title="Playground">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>

  <Tab title="Local">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>
</Tabs>

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

**Expected response:**

```json theme={null}
{
  "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.

<Tabs>
  <Tab title="Record an impression">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>

  <Tab title="Record a click">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>

  <Tab title="Record a conversion">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>
</Tabs>

**Response (201 Created):**

```json theme={null}
{
  "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?

<CardGroup cols={2}>
  <Card title="Computed Values" icon="calculator" href="/tutorials/computed-values">
    Learn how to define formula-based fields for per-customer personalization.
  </Card>

  <Card title="API Tutorial" icon="code" href="/tutorials/api-tutorial">
    Deep dive into the Recommend and Respond APIs with advanced features.
  </Card>

  <Card title="Composable Pipeline" icon="puzzle-piece" href="/data/transforms/composable-pipeline">
    Build advanced Decision Flows with the v2 node-based pipeline.
  </Card>

  <Card title="Contact Policies" icon="shield" href="/decisioning/contact-policies">
    Set up frequency caps and suppression rules.
  </Card>

  <Card title="Behavioral Metrics" icon="chart-bar" href="/studio/behavioral-metrics">
    Create computed metrics from interaction history.
  </Card>

  <Card title="MCP Quickstart" icon="plug" href="/tutorials/mcp-quickstart">
    Connect your AI IDE to KaireonAI for natural-language configuration.
  </Card>
</CardGroup>